VFF Optimizer

A Django-based toolkit for generating, visualizing, and relaxing atomistic semiconductor hetero-nanoparticles with a Keating Valence Force Field.
Built for core/shell nanostructures, strain analysis, 3D inspection, and reproducible browser-based workflows.

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

---

Purpose And Scope

VFF Optimizer is a web application for classical geometry relaxation of atomistic semiconductor nanostructures. It combines a structure generator, a Keating-style valence force field optimizer, asynchronous task execution, result downloads, strain plots, and a documentation overlay styled after the Mendelevium project documentation system.

This is a classical force-field relaxation tool, not an electronic-structure code.

The application does not calculate band gaps, charge transfer, ionicity beyond equilibrium parameters, chemical reactions, or bond breaking. For electronic properties, use the relaxed structure as input for DFT or another electronic-structure method.

---

Design Philosophy

This is a geometry-preparation and strain-relaxation tool, not a replacement for quantum-mechanical simulation.

The project is built around a pragmatic scientific workflow: generate a plausible atomistic heterostructure, relax local strain with a classical Keating Valence Force Field, inspect the result, and export clean coordinates for downstream calculations. The browser UI is there to make that loop inspectable and repeatable rather than hiding it behind a one-shot script.

The model favors transparent assumptions over black-box prediction. Material parameters, shape construction, task execution, and generated outputs are kept visible so users can audit what changed between an input structure and the relaxed result.

---

Why VFF Instead Of DFT?

Density-functional theory is the right tool for electronic properties, but it is often too expensive for quickly exploring large hetero-nanoparticle geometries. VFF relaxation is useful earlier in the workflow: it can remove unrealistic local strain, compare shape families, and prepare candidate structures before a more expensive electronic-structure calculation.

This separation is intentional: VFF Optimizer prepares and analyzes geometry; DFT or another electronic-structure method should be used for band structure, charge density, optical transitions, and publication-grade electronic conclusions.

---

Core Features

Feature	Details
Structure generator	Nanorods, nanowires, quantum dots, platelets, tubes, branched rods, bipods, tetrapods, sea-urchin shells, and curved shell variants.
Core/shell systems	Flexible core-shell geometry with material presets and manual parameter override.
VFF optimization	Keating-style bond-stretching and angle-bending relaxation for heterostructure strain minimization.
Async execution	Celery worker and Redis broker keep long optimizations outside the web request cycle.
Live progress	Django Channels/WebSockets stream task progress and status updates to the browser.
3D viewer	3Dmol.js viewer for uploaded, generated, and relaxed XYZ structures.
Strain analysis	Horizontal and vertical bond-length distribution plots generated from relaxed structures.
Upload validation	UTF-8 .xyz uploads with extension and size limits.
Documentation UI	The in-app docs overlay uses the unified Mendelevium-style docs template CSS.
Deployment paths	Local Django, Docker Compose, and Oracle/Caddy deployment patterns are documented.

---

Model Boundaries

The optimizer is intentionally focused: it relaxes atomic coordinates under a classical VFF model. That makes it fast and useful for geometry preparation, but it also defines clear boundaries.

• No quantum mechanics or self-consistent electronic structure.
• No charge-density, band-gap, or optical-transition calculation.
• No chemical reaction pathway or bond-breaking simulation.
• No automatic validation that a material parameter set is publication-grade for a new system.
• Boundary rounding and generator shapes are geometric construction tools, not thermodynamic growth models.

CdS and CdSe parameters are treated as project-curated values. Other built-in presets are practical starting points and should be checked, cited, or refined before publication-grade use.

---

Requirements

Requirement	Why It Is Needed
Python 3.11	Runtime used for Django, SciPy, Celery, and the VFF optimization stack.
Redis	Required for Celery background jobs and Django Channels/WebSocket messaging.
Python packages from requirements.txt	Django/ASGI, numerical optimization, plotting, static serving, database URL parsing, and deployment helpers.
Modern browser	Needed for the web UI, 3Dmol.js molecular viewer, Chart.js plots, and documentation overlay.
PostgreSQL	Optional but recommended for public multi-user deployments. SQLite is fine for local tests.
Docker + Docker Compose	Optional deployment path for Redis, Daphne, Celery worker, Celery beat, and Caddy.

The project currently targets python-3.11.11 via runtime.txt. The frontend loads 3Dmol.js, Chart.js, and MathJax from CDNs, so production hosts need outbound browser access to those resources unless they are self-hosted.

---

Quick Start

Option A: Local Web App

git clone https://github.com/Gotili/VFF_Optimizer.git
cd VFF_Optimizer
python -m venv .venv
. .venv/Scripts/activate      # Windows PowerShell: .venv\Scripts\Activate.ps1
pip install -r requirements.txt
cp .env.example .env          # Windows PowerShell: Copy-Item .env.example .env
python manage.py migrate
python manage.py runserver

Open http://127.0.0.1:8000/.

For optimization jobs, start Redis and a Celery worker in separate terminals:

redis-server
celery -A vff_project worker --loglevel=info --concurrency=1

Option B: Docker Compose

cp .env.example .env
cp Caddyfile.example Caddyfile
# Edit .env and Caddyfile for your hostnames.
docker compose up --build

The compose stack starts Redis, Daphne, Celery worker, Celery beat, and Caddy.

Option C: Legacy Local CLI

run_local.py remains available for command-line optimization from input.txt and local .xyz files. See LOCAL_RUN.md for the full workflow.

---

Example Input

Project links:

Link	URL
Live demo	bourier.biz
Repository	github.com/Gotili/VFF_Optimizer

The repository includes:

File	Purpose
225-43-29-center-dot-CdSeCdS.xyz	Ready-to-use CdSe/CdS example structure.
input.txt	Legacy CLI configuration used by run_local.py.

The example file is intentionally kept in the repository so a fresh checkout can run a meaningful local test without private data.

---

Architecture

flowchart TD
    Browser[Browser UI] --> Django[Django Views]
    Browser <--> Channels[Django Channels / WebSocket]
    Django --> DB[(Database)]
    Django --> Celery[Celery Task Queue]
    Celery --> Redis[(Redis Broker)]
    Channels --> Redis
    Celery --> Engine[VFF Engine]
    Engine --> Analysis[Strain Plot Analysis]
    Analysis --> Media[Generated Media]
    Django --> Static[Static CSS / Docs Template]

Loading

Module	Responsibility
simulation/views.py	Uploads, generator previews, job creation, downloads, and API endpoints.
simulation/engine.py	XYZ parsing, topology construction, VFF energy terms, optimization, and XYZ export.
simulation/generator.py	Structure generation parameters and endpoint integration.
simulation/shapes.py	Shape construction, rounded-edge handling, masks, and geometry utilities.
simulation/vff_params.py	Material systems, bond parameters, angle parameters, and UI-facing presets.
simulation/analysis.py	Bond-length and strain-plot generation.
simulation/tasks.py	Celery optimization jobs.
simulation/tasks_periodic.py	Cleanup of old generated simulations/media.
simulation/templates/	Main UI, generator modal, config modal, and documentation overlay.
simulation/static/css/docs.css	Mendelevium-style documentation template CSS.

---

Environment Variables

Required for production:

SECRET_KEY='generate-a-real-django-secret-key'
DEBUG=False
ALLOWED_HOSTS=your-domain.example,www.your-domain.example
CSRF_TRUSTED_ORIGINS=https://your-domain.example,https://www.your-domain.example
ALLOWED_DOWNLOAD_REFERER_HOSTS=your-domain.example,www.your-domain.example
REDIS_URL=redis://redis:6379/0

Optional but useful for embedded deployments:

CSP_CONNECT_SRC_EXTRA=wss://your-domain.example
CSP_FRAME_ANCESTORS=https://your-parent-site.example
DATABASE_URL=postgresql://user:password@host:5432/database
SECURE_SSL_REDIRECT=False

Quote SECRET_KEY in .env; Django-generated keys may contain $, which Docker Compose otherwise treats as variable interpolation.

If DATABASE_URL is not set, the app uses local SQLite. SQLite is fine for local tests; PostgreSQL is recommended for a public multi-user deployment.

---

Deployment

Docker / Caddy

• Dockerfile builds the Django/ASGI application image.
• docker-compose.yml starts Redis, web, worker, beat, and Caddy.
• Caddyfile.example is a safe public template.
• The real Caddyfile is ignored because it contains deployment hostnames.

The CSS assets are committed. Docker does not download Tailwind at build time, which keeps deployments deterministic and avoids a GitHub binary download during image creation.

Oracle Cloud

Oracle deployment can use local ignored helper files such as:

• deploy_to_oracle.ps1
• deploy_to_oracle.sh
• sync_to_oracle.ps1
• Caddyfile
• .env

For a private Oracle VM, keep machine-specific deployment helpers outside Git and adapt them locally from the documented Docker Compose setup. A typical Windows workflow with PuTTY looks like this:

powershell -ExecutionPolicy Bypass -File .\deploy_to_oracle.ps1 -VmUser <ssh-user> -VmIp <server-ip-or-hostname> -PuttyKeyPath "C:/path/to/private-key.ppk"

The local helper uploads a release archive, keeps the server .env unless -RefreshEnv is passed, appends missing environment keys, rebuilds Docker Compose, and writes .deploy_version on the server. To verify a deploy manually:

plink -i "C:/path/to/private-key.ppk" <ssh-user>@<server-ip-or-hostname> "cd ~/valence_force_field && cat .deploy_version && docker-compose ps"

Local Oracle helper files are intentionally not part of the public repository. Keep VM IPs, SSH key paths, generated secrets, hostnames, and deployment tokens in ignored local files only.

---

Verification

Run these before publishing a tag:

SECRET_KEY=test-key DEBUG=True python manage.py check
SECRET_KEY=test-key DEBUG=True python manage.py test simulation
SECRET_KEY=test-key DEBUG=False ALLOWED_HOSTS=localhost,127.0.0.1 CSRF_TRUSTED_ORIGINS=http://localhost,http://127.0.0.1 python manage.py collectstatic --dry-run --noinput

Current release-candidate status:

Check	Result
Django dev system check	Passing
Django production-like system check	Passing
Simulation test suite	16 / 16 passing
Static asset discovery	Passing
Root page render smoke	Passing
Headless screenshot smoke	Passing

---

Design Decisions

Django + Celery + Redis

Optimization jobs can take longer than a request/response cycle should own. Celery keeps the numerical work outside the web request path, while Django Channels streams progress back to the UI.

Committed CSS Assets

The release keeps generated CSS assets in the repository. That makes Docker and Oracle deployments deterministic and avoids downloading Tailwind or rebuilding CSS during production image creation.

Session-Scoped Results

Simulation ownership is tracked through Django sessions. The download endpoint also keeps a documented referer fallback for embedded deployments where browser cookie behavior can be restrictive. A signed download token flow is the preferred future hardening path.

Documentation Template Reuse

The in-app docs use the same visual language as the Mendelevium documentation pages. The styling lives in simulation/static/css/docs.css so documentation content can evolve without rebuilding the application shell.

---

Related Documents

Document	Purpose
LOCAL_RUN.md	Practical local commands for web, Celery, and legacy CLI runs.
RELEASE_AUDIT.md	Current release-readiness notes, checks, and known risks.
CHANGELOG.md	Human-readable release notes.
SECURITY.md	Security model and vulnerability-reporting guidance.
CONTRIBUTING.md	Development setup and contribution expectations.
CITATION.cff	GitHub-readable citation metadata.

---

Repository Hygiene

Tracked source files are kept to application code, templates, static assets, tests, examples, and deployment templates. Generated or machine-local files are ignored:

• .env, .env.*
• db.sqlite3
• media/
• staticfiles/
• __pycache__/, *.pyc
• .codex-backups/
• local Oracle/Caddy helper scripts
• copied README templates such as READMEx.md

If you add new generated assets, update .gitignore before committing.

---

Security Notes

• SECRET_KEY is required through the environment and must never be committed.
• The admin URL is not the default /admin/ route.
• Uploads are restricted to UTF-8 .xyz files and a 5 MB size limit.
• Production cookies use secure settings for iframe-compatible deployments.
• Download authorization is session-based with a referer fallback for embedded contexts; a signed token flow would be a stronger future improvement.
• Caddy should terminate HTTPS in production.

---

Release Checklist

1. Confirm .env, Caddyfile, Oracle helper scripts, databases, media, and backups are not staged.
2. Run the verification commands above.
3. Review RELEASE_AUDIT.md.
4. Confirm CITATION.cff, SECURITY.md, CONTRIBUTING.md, and CHANGELOG.md are included.
5. Confirm material parameters are appropriate for the intended scientific use.
6. Manually open the app once in a browser and test upload, generator preview, docs overlay, and optimization queue.
7. Tag the release and cite the tag in any research output.

---

Citation

If you use this project in research, cite the VFF method and the exact release tag of this repository. GitHub can also read the repository metadata from CITATION.cff.

@software{bourier2026vffoptimizer,
  author  = {Bourier, Felix Sébastien},
  title   = {VFF Optimizer: Geometry Optimization Toolkit for Atomistic Semiconductor Hetero-Nanoparticles},
  year    = {2026},
  version = {2.0.0},
  url     = {https://github.com/Gotili/VFF_Optimizer}
}

---

📄 License

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

---

Classical strain relaxation for atomistic semiconductor heterostructures.
Generate, inspect, relax, and export reproducible VFF geometries from one browser-based workflow.