KineticsEngine (FELIX)

A browser-accessible workbench for exploring and fitting gold nanoparticle nucleation and growth kinetics.
Finke-Watzky-inspired nonlinear ODE simulation, reference-case evaluation, dataset mapping, and worker-oriented fitting from one inspectable workflow.

Live Demo: bourier.biz | Repository: github.com/Gotili/Kinetics_Engine_FELIX

---

Purpose And Scope

KineticsEngine (FELIX, Fast Equation Logical Investigation eXperiment) models gold nanoparticle formation as a nonlinear reaction-kinetics problem. It combines an explicit scientific core, a Django API and fit-job lifecycle, and a React/Vite workbench for simulation, parameter exploration, dataset compatibility checks, and curve fitting.

The primary model is a gold-surface mechanism with continuous nucleation, autocatalytic growth, time-dependent particle size, and derived surface diagnostics. Analytical first- and second-order A -> B mechanisms provide rate-law references with the same simulation, dataset-mapping, and fitting contract. The application is intended to make assumptions, parameter ranges, and fitted artifacts inspectable rather than hiding them behind a single opaque result.

---

Model Boundaries

This is a reaction-kinetics workbench, not an electronic-structure package or a quantum-chemistry solver.

The project does not calculate electronic bands, charge density, optical transitions, atomistic geometry relaxation, or reaction pathways from first principles. Its outputs should be interpreted within the stated ODE model, parameter ranges, and supplied reference data. Validate model choices and fitted parameters before using them in publication-grade conclusions.

---

Core Features

Feature	Details
Scientific core	Portable Python package for mechanisms, simulation, evaluation, fitting helpers, and compute planning.
Mechanism library	Finke-Watzky-inspired gold-surface kinetics plus analytical first- and second-order A -> B reference models, all exposed through one simulation and fitting contract.
Interactive workbench	React 18/Vite frontend for parameter overrides, time-series inspection, dataset mapping, and fitting requests.
Django API	Typed request validation, mechanism discovery, simulation/evaluation endpoints, record persistence, and runtime health endpoints.
Fit-job lifecycle	Queue-aware fit jobs with local worker execution, leases, retries, artifacts, export bundles, and external-dispatch contracts.
Documentation	In-app documentation uses a shared, theme-aware template with keyboard navigation, focus handling, and responsive layout.
Deployment	Local development, Docker Compose, reverse-proxy, and Oracle-oriented deployment notes are included.

---

Requirements

Requirement	Purpose
Python 3.11+	Scientific core, Django API, workers, and tests.
Node.js 20+	React/Vite frontend build.
npm	Install frontend lockfile dependencies.
Docker + Docker Compose	Optional local container stack.
Modern browser	Workbench, charts, and docs overlay.

---

Quick Start

Local Development

# From the repository root
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e .\scientific_core -e .\backend

Copy-Item .\infra\.env.example .\infra\.env
# Edit infra/.env: replace the Django secret and set the hosts for your machine.

Set-Location frontend
npm ci
npm run dev

In a second terminal, from the repository root with the virtual environment active:

$repoRoot = (Get-Location).Path
$env:PYTHONPATH = "$repoRoot\backend\src;$repoRoot\scientific_core\src"
Set-Location "$repoRoot\backend"
python manage.py migrate
python manage.py runserver 127.0.0.1:8000

Open the Vite URL shown by the frontend, normally http://127.0.0.1:4174. Start python manage.py run_fit_job_worker in a third terminal when using the asynchronous fit-job path.

Docker Compose

cp infra/.env.example infra/.env
# Edit infra/.env before exposing the stack.
docker compose --env-file infra/.env -f infra/docker-compose.local.yml up --build

The compose profile starts Django, a local fit-job worker, and an Nginx-served Vite build. It is a local/single-operator baseline, not an automatic multi-tenant deployment.

---

Verification

Run these checks before a release:

# From the repository root
$repoRoot = (Get-Location).Path

# Scientific core
$env:PYTHONPATH = "$repoRoot\scientific_core\src"
Set-Location "$repoRoot\scientific_core"
python -m unittest discover -s tests -v

# Backend
$env:PYTHONPATH = "$repoRoot\backend\src;$repoRoot\scientific_core\src"
Set-Location "$repoRoot\backend"
python -m unittest discover -s tests -v
python manage.py check
python manage.py makemigrations --check --dry-run

# Frontend
Set-Location "$repoRoot\frontend"
npm ci
npm run build

GitHub Actions runs the same scientific-core, backend, Django/migration, and frontend-build checks for pushes and pull requests.

---

Architecture

flowchart TB
    subgraph workbench["Interactive Workbench"]
        ui["React and Vite UI"]
        docs["Unified Documentation"]
    end

    subgraph runtime["Django Runtime"]
        api["API and Contracts"]
        store[("Runtime Record Store")]
        queue["Fit Job Queue"]
        worker["Local Fit Worker"]
    end

    subgraph science["Scientific Core"]
        core["Kinetics Models and Fit Engine"]
    end

    ui --> api
    ui -. Documentation .-> docs
    api --> core
    api --> store
    api --> queue
    queue --> worker
    worker --> core

Loading

Area	Responsibility
scientific_core/	Mechanisms, numerical simulation, fitting utilities, reference cases, validation, and CLI.
backend/	Django project, API serializers/views, persistence, job execution, worker commands, and runtime endpoints.
frontend/	React workbench, API client, theme bridge, charts, controls, and documentation overlay.
infra/	Container and Nginx examples plus Oracle deployment guidance.
docs/	Embed contract, UI handoff notes, and deployment documentation.

---

Deployment And Security

• Copy infra/.env.example to the ignored infra/.env; do not deploy with example values.
• Use a generated GOLD_KINETICS_SECRET_KEY, explicit GOLD_KINETICS_ALLOWED_HOSTS, HTTPS, and the intended CSP embedding parents.
• Keep runtime records, SQLite databases, reports, logs, SSH keys, and Oracle-specific helpers out of Git.
• Configure GOLD_KINETICS_FRAME_ANCESTORS explicitly when embedding the frontend in another origin.

See infra/ORACLE_DEPLOYMENT.md, LOCAL_DEV.md, and SECURITY.md.

---

Repository Hygiene

The public source release contains code, tests, docs, examples, and deployment templates. Generated frontend output, runtime data, local databases, logs, editor state, credentials, and historical local research archives are excluded via .gitignore; nothing is deleted from a local working copy by that policy.

---

Citation

If you use the project in research, cite the exact release tag and consult CITATION.cff.

@software{bourier2026kineticsengine,
  author  = {Bourier, Felix Sebastien},
  title   = {KineticsEngine (FELIX): Gold Nanoparticle Kinetics Workbench},
  year    = {2026},
  version = {1.0.0},
  url     = {https://github.com/Gotili/Kinetics_Engine_FELIX}
}

---

📄 License

Released under the MIT License. Copyright © 2026 Dr. Felix Sébastien Bourier.

---

Kinetics is only useful when its assumptions remain inspectable.