stochastic-flock 0.1.0__tar.gz

stochastic_flock-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,69 @@
+name: Build and Upload to PyPI
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [ main ]
+  release:
+    types: [published, created, released] # Added more types for safety
+
+jobs:
+  build_wheels:
+    name: Build wheels on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+    
+        os: [ubuntu-latest, windows-latest, macos-14]
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Build wheels
+        uses: pypa/cibuildwheel@v2.21.3
+        env:
+          # Only CPython 3.10+, No PyPy (fixes your previous error)
+          CIBW_SKIP: pp* cp36-* cp37-* cp38-* cp39-* *-win32 *-manylinux_i686
+          # manylinux_2_28 provides GCC 11/12 for C++20 support
+          CIBW_MANYLINUX_X86_64_IMAGE: manylinux_2_28
+          CIBW_BUILD_VERBOSITY: 1
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: cibw-wheels-${{ matrix.os }}-${{ strategy.job-index }}
+          path: ./wheelhouse/*.whl
+
+  build_sdist:
+    name: Build source distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - name: Build sdist
+        run: pipx run build --sdist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: cibw-sdist
+          path: dist/*.tar.gz
+
+  upload_pypi:
+    needs: [build_wheels, build_sdist]
+    runs-on: ubuntu-latest
+    # This job only runs when you actually publish a "Release" on GitHub
+    if: github.event_name == 'release' || github.event_name == 'workflow_dispatch'
+    permissions:
+      id-token: write # Mandatory for Trusted Publishing
+      contents: read
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: cibw-*
+          path: dist
+          merge-multiple: true
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

stochastic_flock-0.1.0/.gitignore

@@ -0,0 +1,34 @@
+# 1. Ignore everything by default
+*
+
+# 2. Allow all directories so Git can search them
+!*/
+
+# 3. Un-ignore C++ and Project Metadata files (anywhere)
+!*.cpp
+!*.hpp
+!*.h
+!*.gitignore
+!*.txt
+!*.toml
+!*.md
+!Makefile
+!.github/
+!.github/workflows/*.yml
+
+# 4. Handle Python files:
+# We DON'T un-ignore *.py globally (this keeps root .py files ignored).
+# Instead, we only un-ignore the specific folder you want:
+!src/stochastic_flock/
+!src/stochastic_flock/*.py
+
+# 5. Standard cleanup (Re-ignore build artifacts)
+build/
+build_pgo/
+build_native/
+dist/
+__pycache__/
+*.egg-info/
+*.so
+.venv/
+src/stochastic_flock/__init__.py

stochastic_flock-0.1.0/CMakeLists.txt

@@ -0,0 +1,92 @@
+cmake_minimum_required(VERSION 3.18)
+project(stochastic_flock LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+# 1. Dependencies (Eigen)
+include(FetchContent)
+set(EIGEN_BUILD_PKGCONFIG OFF CACHE BOOL "" FORCE)
+set(EIGEN_BUILD_DOC OFF CACHE BOOL "" FORCE)
+set(BUILD_TESTING OFF CACHE BOOL "" FORCE)
+set(EIGEN_LEAVE_TEST_IN_ALL_TARGET OFF CACHE BOOL "" FORCE) 
+set(EIGEN_BUILD_TESTING OFF CACHE BOOL "" FORCE)            
+
+FetchContent_Declare(
+    eigen
+    GIT_REPOSITORY https://gitlab.com/libeigen/eigen.git
+    GIT_TAG 3.4.0
+)
+
+# Use the "manual" population instead of MakeAvailable 
+# so we can use EXCLUDE_FROM_ALL
+FetchContent_GetProperties(eigen)
+if(NOT eigen_POPULATED)
+    FetchContent_Populate(eigen)
+    # The EXCLUDE_FROM_ALL flag here is the magic bit.
+    # It tells CMake: "Build this, but don't install its files."
+    add_subdirectory(${eigen_SOURCE_DIR} ${eigen_BINARY_DIR} EXCLUDE_FROM_ALL)
+endif()
+
+find_package(Python3 COMPONENTS Interpreter Development.Module REQUIRED) #added .Module
+
+# if(NOT pybind11_FOUND)
+#     execute_process(
+#         COMMAND "${Python3_EXECUTABLE}" -m pybind11 --cmakedir
+#         OUTPUT_VARIABLE pybind11_DIR
+#         OUTPUT_STRIP_TRAILING_WHITESPACE
+#         ERROR_QUIET
+#     )
+# endif()
+
+# # Now find it (using the path discovered above if necessary)
+# find_package(pybind11 REQUIRED)
+
+find_package(pybind11 QUIET)
+
+# If not found, fall back to your manual search (works for your local build)
+if(NOT pybind11_FOUND)
+    execute_process(
+        COMMAND "${Python3_EXECUTABLE}" -m pybind11 --cmakedir
+        OUTPUT_VARIABLE pybind11_DIR
+        OUTPUT_STRIP_TRAILING_WHITESPACE
+        ERROR_QUIET
+    )
+    find_package(pybind11 REQUIRED PATHS ${pybind11_DIR} NO_DEFAULT_PATH)
+endif()
+
+# 3. Define Optimization Settings (Interface Library)
+# This replaces your 'foreach' loop logic
+add_library(sim_opts INTERFACE)
+target_compile_definitions(sim_opts INTERFACE EIGEN_RUNTIME_NO_MALLOC)
+
+if(NOT MSVC)
+    target_compile_options(sim_opts INTERFACE -O3 -ffast-math -Wall)
+    if(NATIVE_OPTIM)
+        target_compile_options(sim_opts INTERFACE -march=native)
+        include(CheckIPOSupported)
+        check_ipo_supported(RESULT lto_supported)
+        if(lto_supported)
+            set_property(TARGET sim_opts PROPERTY INTERFACE_INTERPROCEDURAL_OPTIMIZATION TRUE)
+        endif()
+    endif()
+endif()
+
+pybind11_add_module(stochastic_flock src/python_bindings.cpp)
+target_include_directories(stochastic_flock PRIVATE src)
+target_link_libraries(stochastic_flock PRIVATE Eigen3::Eigen sim_opts)
+
+install(TARGETS stochastic_flock DESTINATION stochastic_flock)
+
+#TODO : ^^^ doesnt install to stochastic_flock folder. perhaps completely remove coupled makefile with bird_solver and python?
+
+
+# 5. Target: Optional SFML (Skipped during Python build)
+if(NOT SKBUILD)
+    find_package(SFML 2.5 COMPONENTS graphics window system QUIET)
+    if(SFML_FOUND)
+        add_executable(bird_solver src/bird_solver.cpp)
+        target_include_directories(bird_solver PRIVATE src)
+        target_link_libraries(bird_solver PRIVATE Eigen3::Eigen sfml-graphics sfml-window sfml-system sim_opts)
+    endif()
+endif()

stochastic_flock-0.1.0/Makefile

@@ -0,0 +1,41 @@
+# 1. Path to your virtual environment's python
+# This ensures we use your .venv even if it isn't "activated" in the terminal
+PYTHON = $(shell pwd)/.venv/bin/python3
+THREADS = $(shell nproc)
+
+init:
+	$(PYTHON) -m pip install -e .
+all:
+# Only configure if the build directory doesn't exist
+	@if [ ! -d "build" ]; then \
+		cmake -B build -S . -DCMAKE_BUILD_TYPE=Release -DPython3_EXECUTABLE=$(PYTHON); \
+	fi
+# Use -j to use all CPU cores
+	cmake --build build -j $(THREADS)
+	cp build/stochastic_flock*.so src/stochastic_flock
+
+native:
+	cmake -B build_native -S . -DCMAKE_BUILD_TYPE=Release -DNATIVE_OPTIM=ON -DPython3_EXECUTABLE=$(PYTHON)
+	cmake --build build_native -j $(THREADS)
+
+pgo: #only does bird_solver PGO
+
+	cmake -B build_pgo -S . -DCMAKE_BUILD_TYPE=Release -DNATIVE_OPTIM=ON -DCMAKE_CXX_FLAGS="-fprofile-generate" -DPython3_EXECUTABLE=$(PYTHON)
+	cmake --build build_pgo --target bird_solver -j $(THREADS)
+
+	./build_pgo/bird_solver
+	
+	cmake -B build_pgo -S . -DCMAKE_BUILD_TYPE=Release -DNATIVE_OPTIM=ON -DCMAKE_CXX_FLAGS="-fprofile-use" -DPython3_EXECUTABLE=$(PYTHON)
+	cmake --build build_pgo --target bird_solver  -j $(THREADS)
+
+debug:
+	cmake -B build_debug -S . -DCMAKE_BUILD_TYPE=Debug -DCMAKE_CXX_FLAGS="-fsanitize=address,undefined" -DPython3_EXECUTABLE=$(PYTHON)
+	cmake --build build_debug  -j $(THREADS)
+
+clean:
+	rm -rf build build_native build_debug build_pgo *.so *.gcda dist
+
+help:
+	@echo "all:    Standard build"
+	@echo "native: Fast build with native hardware optimizations"
+	@echo "pgo:    Profile guided optimization + native build, max performance"

stochastic_flock-0.1.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.2
+Name: stochastic_flock
+Version: 0.1.0
+Summary: Unified Bird Flocking Simulation (1D & 2D)
+Author-Email: Michael Stavreff <Mstavreff@outlook.com>
+Requires-Python: >=3.8
+Requires-Dist: numpy
+Description-Content-Type: text/markdown
+
+
+
+# High Performance C++ Flocking Simulation for Stochastic Modelling
+> *Michael Stavreff,*
+> *December 17, 2025*
+## Development & Compilation
+
+This project uses **CMake** and a **Makefile** to manage the C++ build process, dependencies (Eigen, pybind11), and performance optimizations.
+
+### Prerequisites
+
+To build the project from source, you will need:
+* **C++20 Compiler** (GCC 10+ or Clang 11+)
+* **CMake** (3.18+)
+* **Python 3.8+** (with `python3-venv` and `python3-dev`)
+* **SFML 2.5** (Optional: only required for the visual standalone solver)
+  ```bash 
+  sudo apt install libsfml-dev
+  ```
+
+### Developer Setup
+1. Clone and create a virtual environment:
+
+```Bash
+git clone https://github.com/Mstavreff/stochastic_flock.git
+cd stochastic_flock
+python3 -m venv .venv
+source .venv/bin/activate
+```
+2. Install build dependencies:
+```Bash
+pip install -r requirements.txt
+```
+
+### Building the Project
+The provided Makefile contains shortcuts for common build scenarios.
+1. Standard Build (Python + C++ Solver)
+Compiles the Python module into the root directory and the standalone solver into build/.
+
+```Bash
+make
+```
+2. Native Hardware Optimization
+Compiles using -march=native and -ffast-math. This produces the fastest possible binary for your specific CPU but is not portable to other hardware.
+
+```Bash
+make native
+```
+3. Profile-Guided Optimization (PGO) + Native 
+For maximum performance, use PGO to optimize code paths based on simulation data. Uses ```tuning.py``` to instrument and recompiles using native flags.
+```Bash
+make pgo
+```
+4. Debug Mode
+Compiles with debug symbols (-g) and Undefined Behavior Sanitizers for use with GDB/LLDB.
+
+```Bash
+make debug
+```
+### Python Usage
+
+If you simply wish to use the simulation in a Python environment without modifying the C++ source:
+
+```Bash
+pip install stochastic_flock
+```
+For local development, after running make, you can import the module directly in the root directory:
+
+```Python
+>>> import stochastic_flock
+>>> sim = stochastic_flock.Simulation2d(params, seed)
+```
+## Introduction
+Financial markets have famously exhibited flocking or herding behavior, most famously during crises and impending crashes. Such movements typically are completely unpredictable; the aim of this paper is to explore whether these movements are compltely unable to be modelled or are instead the product of some highly non-linear behavior requiring a novel approach. Naturally, birds in large flocks are an interesting candidate to model such emergent behavior in financial markets. Large flocks exhibit features which must be re-interpreted to a financial context, particularly in attraction, repulsion, turning behavior, and in the context of the particular paper, leader/follower dynamics:
+
+### Reference Paper Overview
+*The original paper is given here: https://arxiv.org/abs/2010.01990.* While the paper is short and concise and absolutely worth a read, some important details will be repeated. 
+
+Cristiani et al.'s paper puts forward a second-order, delayed, stochastic differential equation to describe accelerations of bird agents. The stochastic element stems from birds having an exponential process (geometric in approximation) describing a follower -> leader transition where any attractive forces are dropped in their acceleration calculation and causing only repulsive-force trajectories. Additionally, birds react to the positions of others in a rank-ordered system of the nearest M birds, irregardless of distance; they also react to the delayed positions rather than the most instant information, something which creates more heavy movements and drifting of flocks in practice. These behaviors underline various interpretations worth discussing in the paper, mostly regarding trader behaviors or modelling portfolios of correlated equities in a sector which may be driven by such "social" forces and similarly experience shocks or new information in the form of a leader bird. 

stochastic_flock-0.1.0/README.md

@@ -0,0 +1,79 @@
+
+
+# High Performance C++ Flocking Simulation for Stochastic Modelling
+> *Michael Stavreff,*
+> *December 17, 2025*
+## Development & Compilation
+
+This project uses **CMake** and a **Makefile** to manage the C++ build process, dependencies (Eigen, pybind11), and performance optimizations.
+
+### Prerequisites
+
+To build the project from source, you will need:
+* **C++20 Compiler** (GCC 10+ or Clang 11+)
+* **CMake** (3.18+)
+* **Python 3.8+** (with `python3-venv` and `python3-dev`)
+* **SFML 2.5** (Optional: only required for the visual standalone solver)
+  ```bash 
+  sudo apt install libsfml-dev
+  ```
+
+### Developer Setup
+1. Clone and create a virtual environment:
+
+```Bash
+git clone https://github.com/Mstavreff/stochastic_flock.git
+cd stochastic_flock
+python3 -m venv .venv
+source .venv/bin/activate
+```
+2. Install build dependencies:
+```Bash
+pip install -r requirements.txt
+```
+
+### Building the Project
+The provided Makefile contains shortcuts for common build scenarios.
+1. Standard Build (Python + C++ Solver)
+Compiles the Python module into the root directory and the standalone solver into build/.
+
+```Bash
+make
+```
+2. Native Hardware Optimization
+Compiles using -march=native and -ffast-math. This produces the fastest possible binary for your specific CPU but is not portable to other hardware.
+
+```Bash
+make native
+```
+3. Profile-Guided Optimization (PGO) + Native 
+For maximum performance, use PGO to optimize code paths based on simulation data. Uses ```tuning.py``` to instrument and recompiles using native flags.
+```Bash
+make pgo
+```
+4. Debug Mode
+Compiles with debug symbols (-g) and Undefined Behavior Sanitizers for use with GDB/LLDB.
+
+```Bash
+make debug
+```
+### Python Usage
+
+If you simply wish to use the simulation in a Python environment without modifying the C++ source:
+
+```Bash
+pip install stochastic_flock
+```
+For local development, after running make, you can import the module directly in the root directory:
+
+```Python
+>>> import stochastic_flock
+>>> sim = stochastic_flock.Simulation2d(params, seed)
+```
+## Introduction
+Financial markets have famously exhibited flocking or herding behavior, most famously during crises and impending crashes. Such movements typically are completely unpredictable; the aim of this paper is to explore whether these movements are compltely unable to be modelled or are instead the product of some highly non-linear behavior requiring a novel approach. Naturally, birds in large flocks are an interesting candidate to model such emergent behavior in financial markets. Large flocks exhibit features which must be re-interpreted to a financial context, particularly in attraction, repulsion, turning behavior, and in the context of the particular paper, leader/follower dynamics:
+
+### Reference Paper Overview
+*The original paper is given here: https://arxiv.org/abs/2010.01990.* While the paper is short and concise and absolutely worth a read, some important details will be repeated. 
+
+Cristiani et al.'s paper puts forward a second-order, delayed, stochastic differential equation to describe accelerations of bird agents. The stochastic element stems from birds having an exponential process (geometric in approximation) describing a follower -> leader transition where any attractive forces are dropped in their acceleration calculation and causing only repulsive-force trajectories. Additionally, birds react to the positions of others in a rank-ordered system of the nearest M birds, irregardless of distance; they also react to the delayed positions rather than the most instant information, something which creates more heavy movements and drifting of flocks in practice. These behaviors underline various interpretations worth discussing in the paper, mostly regarding trader behaviors or modelling portfolios of correlated equities in a sector which may be driven by such "social" forces and similarly experience shocks or new information in the form of a leader bird. 

stochastic_flock-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["scikit-build-core>=0.8", "pybind11"] 
+build-backend = "scikit_build_core.build"
+
+
+[project]
+name = "stochastic_flock"
+version = "0.1.0"
+description = "Unified Bird Flocking Simulation (1D & 2D)"
+readme = "README.md"
+requires-python = ">=3.8"
+authors = [
+    {name = "Michael Stavreff", email = "Mstavreff@outlook.com"},
+]
+dependencies = [
+    "numpy",
+]
+
+[tool.scikit-build]
+wheel.packages = ["src/stochastic_flock"]
+editable.mode = "redirect"      
+cmake.args = ["-DSKBUILD=ON"]
+build-dir = "build/{wheel_tag}"

stochastic_flock-0.1.0/requirements.txt

@@ -0,0 +1,11 @@
+# Tools to bridge C++ and Python
+pybind11
+scikit-build-core
+ninja  # Recommended for faster builds
+
+numpy
+eigen  
+
+# Tools for PyPi development
+build
+twine

stochastic_flock-0.1.0/src/bird_solver.cpp

@@ -0,0 +1,47 @@
+#include "constants.hpp"
+#include "simulation.hpp"
+#include "visual.hpp"
+
+#include <Eigen/Dense>
+#include <SFML/Graphics.hpp>
+#include <format>
+#include <random>
+#include <stdexcept>
+#include <string>
+#include <vector>
+
+int main()
+{
+
+    Parameters p;
+    int n_birds = 500;
+    double att = 0.03;
+    double rep = 2.5;
+    std::cout << "birds: ";
+    std::cin >> n_birds;
+    std::cout << "\n";
+    std::cout << "attraction: ";
+    std::cin >> att;
+    std::cout << "\n";
+    std::cout << "repulsion: ";
+    std::cin >> rep;
+    std::cout << "\n";
+
+    p.kWIDTH_2D = 2100;
+    p.kHEIGHT_2D = 1300;
+    p.kREP = rep;
+    p.kATT = att;
+    p.kFRAMERATE = 1000;
+    p.kN_BIRDS = n_birds;
+    p.kROUNDS = 1000000;
+    std::mt19937 mt;
+    mt.seed(std::random_device{}());
+    // mt.seed(50);
+
+    Eigen::Matrix<double, Eigen::Dynamic, 4> positions;
+    positions.resize(p.kN_BIRDS, 4);
+    positions = positions.setRandom() * 100;
+
+    Simulation2d<> Sim(p, mt, positions);
+    init_simulation(Sim);
+}

stochastic_flock-0.1.0/src/constants.hpp

@@ -0,0 +1,9 @@
+#pragma once
+
+inline constexpr int kFRAMERATE{60};
+inline constexpr int kROUNDS{10000};
+// Higher dimensional parameters
+inline constexpr int kTREE_MEDIAN_SAMPLE{30}; // could profile
+inline constexpr int kLEAF_SIZE{16};          // double once using floats to fit SIMD registers better, could profile
+inline constexpr double kPRUNE_EPS{0.01};     // for approximate KD tree pruning
+inline constexpr double kAPPROX_PRUNE_FACTOR{1.0 / ((1.0 + kPRUNE_EPS) * (1.0 + kPRUNE_EPS))};

stochastic_flock-0.1.0/src/python_bindings.cpp

@@ -0,0 +1,74 @@
+#include "simulation.hpp"
+// #include "visual.hpp"
+#include <pybind11/eigen.h>
+#include <pybind11/pybind11.h>
+#include <pybind11/stl.h>
+
+namespace py = pybind11;
+using Sim1d = Simulation1d<Eigen::Dynamic>;
+using Sim2d = Simulation2d<Eigen::Dynamic>;
+void init_simulation(Sim2d &sim);
+
+void bind_parameters(py::module &m)
+{
+    py::class_<Parameters>(m, "Parameters")
+        .def(py::init<>())
+        .def_readwrite("kN_BIRDS", &Parameters::kN_BIRDS)
+        .def_readwrite("kM", &Parameters::kM)
+        .def_readwrite("kDELAY", &Parameters::kDELAY)
+        .def_readwrite("kPT", &Parameters::kPT)
+        .def_readwrite("kPD", &Parameters::kPD)
+        .def_readwrite("kRT", &Parameters::kRT)
+        .def_readwrite("kREP", &Parameters::kREP)
+        .def_readwrite("kALI", &Parameters::kALI)
+        .def_readwrite("kATT", &Parameters::kATT)
+        .def_readwrite("kTIMESTEP", &Parameters::kTIMESTEP)
+        .def_readwrite("kROUNDS", &Parameters::kROUNDS)
+        .def_readwrite("kPROBABILITY", &Parameters::kPROBABILITY)
+        .def_readwrite("kBOX_SIZE", &Parameters::kBOX_SIZE)
+        .def_readwrite("kEPSILON", &Parameters::kEPSILON)
+        .def_readwrite("kBUFFER_CYCLES", &Parameters::kBUFFER_CYCLES); // must be calculated manually in python
+}
+
+PYBIND11_MODULE(stochastic_flock, m)
+{
+    m.doc() = "Agent-Based Bird Flocking Simulation";
+
+    bind_parameters(m);
+
+    py::class_<std::mt19937>(m, "MT19937").def(py::init<uint32_t>());
+
+    // py::class_<Sim1d>(m, "Simulation1d")
+    //     .def(py::init<Parameters &, std::mt19937 &>())
+    //     .def("update",
+    //          [](Sim1d &self) {
+    //              self.update_state();
+    //              self.shift_back();
+    //          })
+    //     .def_property_readonly("states", [](Sim1d &self) { return self.states; })
+    //     .def_property_readonly("positions", [](Sim1d &self) { return self.states.col(0); })
+    //     .def_property_readonly("velocities", [](Sim1d &self) { return self.states.col(1); })
+    //     .def_property_readonly("status", [](Sim1d &self) { return self.states.col(2); })
+    //     .def_property_readonly("timers", [](Sim1d &self) { return self.timer_states; });
+
+    py::class_<Sim2d>(m, "Simulation2d")
+        .def(py::init<Parameters &, std::mt19937 &, const std::optional<Eigen::Matrix<double, Eigen::Dynamic, 4>> &>(),
+             py::arg("params"), py::arg("seed"), py::arg("start_conditions") = std::nullopt)
+        .def("update",
+             [](Sim2d &self) {
+                 self.update_state();
+                 self.shift_back();
+             })
+        .def("debug_tree", &Sim2d::debug_print_tree, py::arg("i") = 0, py::arg("indent") = 0)
+        // .def("show",
+        //      [](Sim2d &self) {
+        //          py::gil_scoped_release release; // Allows other Python threads to run while window is open
+        //          init_simulation_fontless(self);
+        //      })
+
+        .def_property_readonly("states", [](Sim2d &self) { return self.states; })
+        .def_property_readonly("positions", [](Sim2d &self) { return self.states.leftCols(2); })
+        .def_property_readonly("velocities", [](Sim2d &self) { return self.states.middleCols(2, 2); })
+        .def_property_readonly("status", [](Sim2d &self) { return self.states.col(4); })
+        .def_property_readonly("timers", [](Sim2d &self) { return self.timer_states; });
+}