Version: 0.3.0 Author: Olivier Vitrac, PhD, HDR Organization: INRAE + Generative Simulation Last Updated: January 2026

NOTE: Survey is a companion module of SFPPy to offer a graphical user interface (web) equivalent to SFPP3, with several extensions (multiple steps and substances, queuing system, reporting, all SFPPy functionalities). It has been originally designed to run locally, but it can be deployed remotely (note that users and shared projects are not managed in the current version). The installation of SFPPy requires additional steps, in particular, for running the frontend interface.

1. Overview
2. Features at a Glance
3. Installation & Launch
4. User Interface Guide
5. Tab Reference
6. Session Files
7. REST API Reference
8. Export & Reports
9. Offline Operation
10. Workflow Examples
11. Validation Against SFPPy Core
12. Known Limitations
13. Troubleshooting

SFPPy Studio is a web-based graphical user interface for the SFPPy (Safe Food Packaging in Python) framework. It provides an intuitive interface for food contact migration simulation and compliance checking, with support for offline operation and comprehensive safety assessment via ToxTree integration.

studio/
├── app/
│   ├── main.py              # FastAPI application entry point
│   ├── routes/
│   │   ├── assembly.py      # Layer & material management
│   │   ├── substances.py    # PubChem integration, ToxTree, C0 management
│   │   ├── food.py          # Food categories, simulants, geometry
│   │   ├── simulation.py    # Patankar solver interface
│   │   ├── jobs.py          # Background job management
│   │   ├── config.py        # User preferences, solver settings
│   │   ├── exports.py       # Multi-format export (CSV, XLSX, PDF, PNG, SVG)
│   │   ├── sessions.py      # Session file management
│   │   └── fitting.py       # Parameter fitting (D, k) from data
│   ├── templates/
│   │   └── index.html       # Single-page application UI
│   └── static/
│       ├── js/
│       │   ├── app.js           # Frontend JavaScript logic
│       │   ├── service-worker.js # Offline caching
│       │   └── offline-manager.js # Offline state management
│       ├── vendor/              # Vendored CDN dependencies
│       │   ├── chart.min.js     # Chart.js for visualizations
│       │   ├── tailwind-offline.css # Offline CSS fallback
│       │   └── manifest.json    # Vendor dependency manifest
│       └── img/             # Static images
├── data/
│   ├── polymers.yaml        # Polymer database (Tg, Tm, Piringer params)
│   └── examples/            # Example .sfppy.json session files
├── config/                  # User configuration storage
├── jobs/                    # Simulation job storage
├── exports/                 # Generated export files
├── tests/                   # Test suite
├── launcher.py              # CLI launcher script
└── version.py               # Version information

• Python 3.10+ (required by SFPPy core)
• SFPPy core library (patankar module)

No Python installation required — just Docker.

# From SFPPy root directory
docker-compose -f docker/docker-compose.yml up sfppy-studio

Access at: http://localhost:8002

📌 Port can be changed in docker/docker-compose.yml or via:

docker run -p 9002:8002 sfppy-studio

# Clone SFPPy
git clone https://github.com/ovitrac/SFPPy.git
cd SFPPy

# Install with Studio dependencies
pip install -e ".[studio]"

# Launch
python studio/launcher.py

# Install core + studio requirements
pip install -r requirements/core.txt
pip install -r requirements/studio.txt

# Create environment
conda create -n sfppy python=3.10 numpy scipy matplotlib pandas -y
conda activate sfppy

# Clone and install
git clone https://github.com/ovitrac/SFPPy.git
cd SFPPy
pip install -e ".[studio]"

Core SFPPy (see requirements/core.txt):

Studio Web Application (see requirements/studio.txt):

# From the SFPPy root directory
python studio/launcher.py

# With custom port
python studio/launcher.py --port 9002

# With auto-reload for development
python studio/launcher.py --reload

Options:

Default URL: http://127.0.0.1:8002

The UI is organized into nine main tabs plus a top banner with status indicators:

Purpose: Search, select, and configure chemical migrants with safety assessment.

Safety indicators displayed:

• Cramer Class: I (low), II (medium), III (high) toxicological concern
• Genotoxicity: Structural alerts for genotoxic potential
• DNA Binding: Prediction of DNA-reactive structures
• TTC Value: Threshold of Toxicological Concern (µg/person/day)

Purpose: Define the multilayer packaging structure from food-contact to outer layer.

Layer order convention:

• Layer 1 = Food contact layer (nearest to food)
• Layer N = Outer layer (furthest from food)

Purpose: Configure food type, simulant, geometry, and contact conditions.

Geometry parameters:

• Volume (V): Total food volume in contact
• Surface (S): Contact surface area
• V/S ratio: Critical parameter for migration calculation

Purpose: Configure and launch simulation runs.

Purpose: Visualize simulation results and assess compliance.

Compliance calculation:

• Margin = (SML - CF) / SML × 100%
• Green: CF < SML (compliant)
• Red: CF ≥ SML (non-compliant)

Purpose: Manage background simulation jobs.

Purpose: User preferences and solver configuration.

Purpose: Fit diffusion (D) and partition (k) coefficients from data.

Fitting workflow:

1. Load or generate reference data
2. Set initial guesses for D and k
3. Run optimization
4. Review fit quality and residuals
5. Apply fitted values to simulation

Purpose: Documentation and contextual assistance.

SFPPy Studio uses .sfppy.json files for saving/loading complete configurations:

{
  "version": "1.0",
  "metadata": {
    "name": "Example 1: LDPE Film Migration",
    "description": "Migration from 100 um LDPE film",
    "author": "INRAE/[email protected]"
  },
  "geometry": {...},
  "substances": [...],
  "layers": [...],
  "food": {...},
  "contact_steps": [...],
  "simulation_config": {...},
  "results": {...},
  "restart_state": {...}
}

Base URL: http://127.0.0.1:8002/api

Interactive documentation: http://127.0.0.1:8002/docs (Swagger UI)

The PDF export generates a multi-page report:

All exports (PDF, PNG, SVG) include:

• Vertical line from x-axis to CF curve at t_contact
• Horizontal line from curve to y-axis at CF(t_contact)
• Dot at the intersection point
• Labels showing CF value near y-axis and t_c near x-axis

The in-browser report modal includes:

• Substances table with C0, D, k, safety assessment
• Layers table with polymers and thicknesses
• Food & Geometry section with V, S, V/S ratio
• Print-ready white background

SFPPy Studio v0.3.0 introduces full offline capability for environments without internet access.

Structure images are served from:

1. Local cache: patankar/cache.PubChem/thumbs/{cid}.png
2. Fallback: PubChem CDN (if online)

To check available cached images:

curl http://127.0.0.1:8002/api/substances/structure/available

Clear caches via the Config tab or programmatically:

// From browser console
navigator.serviceWorker.controller.postMessage({type: 'CLEAR_CACHE'});

1. Substances Tab: Add "Irganox 1076" and "BHT"
2. Assembly Tab: Select "Monolayer LDPE" preset
3. Substances Tab: Set C0 = 1000 mg/kg for both in Layer 1
4. Food Tab: Select "Fatty foods" → "EU Standard Test"
5. Simulate Tab: Click "Run Simulation"
6. Results Tab: View both substances in CF(t) chart with individual colors

1. Assembly Tab: Add 2 layers
   • Layer 1: gPET, 20 µm (barrier)
   • Layer 2: LDPE, 100 µm
2. Substances Tab: Set C0 = 0 for L1, C0 = 1000 for L2
3. Run simulation and observe lag time

1. Food Tab: Use "Hot Fill" preset
   • Step 1: 30 min at 85°C
   • Step 2: 6 months at 25°C
2. Run simulation with multi-step scenario

1. Substances Tab: Search and add substance
2. Review ToxTree assessment:
   • Cramer Class (I/II/III)
   • Genotoxicity alerts
   • DNA binding potential
3. Check TTC compliance
4. Proceed with simulation if safe

SFPPy Studio has been validated against the SFPPy core examples to ensure numerical accuracy. All simulations use CFtarget (concentration at the specified contact time) for consistency.

Legend:

• Example 1: Irganox 1076 in LDPE film migrating to fatty food
• Example 1 Ext: Two-step simulation with temperature change (chained using >> operator)
• Example 2: Toluene surrogate in PP bottle with/without PET functional barrier
• Example 3: Limonene in wPET/PP/gPET trilayer with set-off → hot-fill → storage sequence

1. Simulation Chaining: Multi-step scenarios use the >> operator pattern from SFPPy core

   • Step 1: multilayer >> food (initial simulation)
   • Step 2+: previous_result >> food (chains with CF0 propagation)

2. Set-off Boundary Conditions: Stacked/rolled configurations supported via setoff classes

3. Temperature-Dependent D: Diffusivity is recalculated at each step's temperature via the food >> layer operator

4. CFtarget vs CF[-1]: Studio uses CFtarget (concentration at contact time) for all compliance calculations, matching the scientific kernel's intended behavior

cd studio
python tests/test_validation.py

• Temperature-dependent D per time step
• Batch simulation mode
• Uncertainty analysis (Monte Carlo)
• Database of measured D, k values
• Integration with EU FCM database
• Full offline ToxTree with local SMARTS rules

Server won't start: "Port already in use"

lsof -i :8002  # Find process
python studio/launcher.py --port 8003  # Use different port

Substance search returns nothing

• Check internet connection (PubChem API)
• Try CID directly: "7519" instead of name
• Use offline cached substances if available

Structure images not loading

• Check local cache: ls patankar/cache.PubChem/thumbs/
• Verify API: curl http://127.0.0.1:8002/api/substances/structure/available

Export fails

• Check matplotlib for PNG/SVG
• Check openpyxl for XLSX

Offline mode not working

• Ensure service worker is registered (check browser DevTools)
• Clear browser cache and reload

python studio/launcher.py --reload

API docs: http://127.0.0.1:8002/docs

Debug endpoint: http://127.0.0.1:8002/api/debug/pubchem-cache

Author: Olivier Vitrac, PhD, HDR Email: [email protected] Organization: INRAE + Generative Simulation

SFPPy Studio v0.3.0 - January 2026