SFPPy - Python Framework for Food Contact Compliance and Risk Assessment 🍏⏩🍎

	This project is part of the Generative Simulation demonstrators	Say it. Simulate it with AI.

---

---

🛠️ Overview

SFPPy is a Python-based framework with ready-to-use Notebooks for compliance testing of food contact materials and recycled plastic safety assessment under:

• 🇺🇸 US FDA regulations | The last FCN list 1698 records is shipped with SFPPy.
• 🇪🇺 European Union regulations (EFSA, EU 10/2011, etc.) | The last Annex I 1194 records is shipped with SFPPy .
• 🇨🇳 Chinese GB standards | The Positive lists A1-A7 1293 records are shipped with SFPPy.
• 🌍 Other international guidelines | SFPPy is already shipped with 2566 substances.

This project implements first-principles chemical migration modeling and introduces a symbolic language and pipelines that AI models can easily parse and manipulate. All substances listed in PubChem can be directly imported and composed into migration scenarios — manually or with AI assistance.

Note

⋆.˚☁️⋆ You can use SFPPy entirely through Google Colab, with no installation and minimal code. GUI-based tools, complete templates, and progressively complex examples are all available through the Colab badges above ( 🎬 full video).

A sister project — SFPPyLite 🌐 — lets you run SFPPy notebooks directly in your browser, with no installation or server required.

📥 SFPPy can be installed locally in any Python (>3.8) environment and work with any notebook manager (see section Quick Start).

Why Notebooks?

Click to expand

📚Notebooks offer a literate and dynamic way to evaluate food safety. They unify problem description, parameterization, simulation, evaluation, and reporting into a single, shareable document. This workflow is ideal for traceability and regulatory validation.
🗣️AI assistants also understand notebooks surprisingly well and can help you interactively. Below is how Gemini (Google's LLM) described the comply.ipynb notebook directly from this link:

📖 Notebook Description | case of notebooks/comply.ipynb

This notebook demonstrates how to evaluate substance migration from a polymeric sleeve into a packaged food simulant using SFPPy. The notebook automates key tasks, including retrieving chemical properties, defining package geometries, applying polymer parameters, and running mass transfer models. It also captures all results and underlying assumptions, providing a clear and traceable record of the simulation process for validation and regulatory assessment.

📌 Short Manual

To demonstrate compliance for a list of substances, a given packaging, and food application using this notebook, follow these steps:

1. Define the migrants. Create a list of migrant objects, one for each substance you want to evaluate. You can use the migrant class to retrieve chemical properties and regulatory data from internal databases.
2. Define the packaging. Use the Packaging3D class to define the geometry of the packaging. You can specify the dimensions and material properties of the packaging.
3. Define the food simulant. Use the food class to define the food simulant. You can specify the type of food, the contact time, and the contact temperature.
4. Run the simulations. Use the %, <<, and >> operators to run the simulations. The % operator injects a substance into the simulation, the << operator inherits properties from the packaging and food simulant, and the >> operator propagates the simulation.
5. Evaluate the results. The results of the simulations are stored in the CF variable. You can use this variable to evaluate the concentration of each substance in the food simulant at the end of the contact time.

📌 Reasoning

These steps are necessary to demonstrate compliance because they ensure that all relevant factors are considered when evaluating the risk of substance migration. By following these steps, you can generate a clear and traceable record of the simulation process that can be used for validation and regulatory assessment

📁 Main Modules (Located in patankar/)

• migration.py 🏗️ - Core solver using a Patankar finite-volume method for mass transfer modeling.
• geometry.py 📐 - Defines 3D packaging geometries and calculates volume/surface area.
• food.py 🍎 - Models food layers and their interactions with packaging.
• layer.py 📜 - Defines materials and layers for multilayer packaging.
• property.py 📊 - Computes physical and chemical properties (e.g., diffusion, partitioning).
• loadpubchem.py 🔬 - Retrieves molecular properties from PubChem (cached locally) and toxicological data from ToxTree.

Why Patankar?

📜 Click to expand

📌 The patankar folder is named in honor of Suhas V. Patankar, who developed and popularized the finite volume method, which this project adapts for mass transfer problems with an arbitrary number of Rankine discontinuities.

📌 The modules include a knowledge management system via extensible classes, allowing easy expansion to cover additional cases and implement new prediction methods.

---

🚀 Quick Start

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

# Install dependencies
pip install -r requirements.txt

Tip

🧭 New to SFPPy? Start with the Wiki Pages for examples, documentation, and guidance.

All examples (example1 to example4) are provided as both Python scripts and Jupyter notebooks. For compliance workflows, notebooks are recommended as they allow you to document your assumptions, inputs, results, and interpretations in one place.

☁️ You can run everything online for free using Google Colab. See installation instructions and the full Colab manual in the wiki.

💻 Prefer local work? Use Jupyter on your machine.

💫 Need a lightweight web version? Try SFPPyLite🌐 in your browser — no setup required — for editing and from basic to advanced calculations. ⚠️ Note: Toxicological assessment via ToxTree is not available and the connectivity to PubChem is more limited.

---

💡 Usage Snippets

SFPPy is fully object-oriented and supports multiple syntax styles, ranging from a functional approach to a more abstract, operator-driven paradigm—all in a Pythonic manner. The snippets below demonstrate both approaches.

Snippet 1️⃣ | Simple Migration Simulation

📜 Click to expand

from patankar.food import ethanol  # food database
from patankar.layer import layer  # material database

# Define the food contact medium and layers
simulant = ethanol() # here a food simulant
A = layer(layername="layer 1 (contact)", D=1e-15, l=50e-6, C0=0, k=1)  # SI units
B = layer(layername="layer 2", D=(1e-9, "cm**2/s"), l=(100, "um"),k=2)
multilayer = A + B  # layer A is contact (food is on the left)

# Run solver, plot the migration kinetics CF(t) and concentration profiles in P Cx(x,t)
solution = simulant.migration(multilayer)
hCF = solution.plotCF()  # concentration kinetic in the simulant (F) for default times
hCx = solution.plotCx()  # concentration profile in the multilayer packaging
# Print in PDF and PNG, export to Excel
hCF.print("myresult")
solution.comparison.save_as_csv("myresult.csv") # CSV format
solution.comparison.save_as_excel("myresult.xlsx") # Excel format

📌 $D$ is the diffusivity, $l$ is the thickness layer, and $C_0$ is the initial concentration.

---

Snippet 2️⃣ | Retrieving Molecular Properties and Toxicological Data

🔍 Click to expand

from patankar.loadpubchem import migrant  # connect to pubchem for missing substances
from patankar.food import oliveoil,water  # food simulants 
from patankar.layer import gPET           # "glassy" PET (i.e., T<Tg)
m = migrant("bisphenol A")                # bisphenol A = BPA
# Print basic properties
print(m.M, m.logP, m.polarityindex)       # Molecular weight, logP value, polarity Index P'
print(m.smiles)                           # CC(C)(C1=CC=C(C=C1)O)C2=CC=C(C=C2)O

# Add BPA to material (P) and food simulants (F1,F2) to calculate binary properties
F1 = oliveoil(migrant=m)                  # F1 = food simulant oliver oil with BPA
F2 = water(migrant=m)                     # F2 = water with BPA
P = gPET(migrant=m)                       # P = PET with BPA
KFP1 = P.k / F1.k     # F-to-P1 partition coefficient, k= Henry-like coefficients
KFP2 = P.k / F2.k     # F-to-P2 partition coefficient, k= Henry-like coefficients
# Print partition coefficients, with k values calculated from Flory-Huggins theory
print(KFP1,KFP2)      # [0.93498524] [0.00093499]

📌 The examples show how to inject m into  $F$=food (various classes ) and $P$=polymer layer (various classes) to get customized and conservative simulations for specific substances and polymers. All properties, diffusivities $D$, Henry-like coefficients $k$ are calculated automatically based from their names.

Add toxicological data from Toxtree

from patankar.loadpubchem import migrantToxtree # combine PubChem and ToxTree
substance = migrantToxtree("formaldehyde")

output

<migrantToxtree object>
               Compound: formaldehyde
                   Name: formaldehyde
                    cid: 712
                    CAS: 50-00-0
                M (min): 30.026
                M_array: [30.026]
                formula: CH2O
                 smiles: C=O
               InChiKey: WSFSSNUMVMOOMR-UHFFFAOYSA-N
                   logP: [1.2]
              P' (calc): [3.91591487]
       ---🇪🇺 EC 10/2011: ---------------
                    SML: 15.0 [mg/kg]
           part a group: of 3 substances
             EC|FCM|REF: 200-001-8|98|1726054880
      ---🇺🇸 US FCN list: ---------------
                 FCM No: 1380
               Notifier: Troy Corporation
           Manufacturer: Troy Corporation
                N. Date: 05/15/2014
   ---🇨🇳 CN GB9685-2016: ---------------
                 FCA No: 0895
          authorized in: ['coatings', 'adhesi [...] , 'paper and board']
          ---𖣂︎ ToxTree: ---------------
            𖣂Toxicology: Low (Class I)
                   𖣂TTC: 1.5 [µg/kg bw/day]
                𖣂CF TTC: 0.09 [mg/kg food intake]
              ⚠️ Alert 1: Alert For Schiff Bas [...] Formation Identified
Out: <migrantToxtree: UN2209 - M=30.026 g/mol>

📌 A local installation of Toxtree (java) is included with SFPPy.

📌 The Annex I of the European FCM and Articles Regulation is integrated as a full database in SFPPy

---

Snippet 3️⃣ | Defining a Custom Packaging Shape

📦 Click to expand

from patankar.geometry import Packaging3D  # import basic shapes
pkg = Packaging3D('bottle', # bottle is a composite shape
                  body_radius=(5, 'cm'), body_height=(0.2, 'm'),
                  neck_radius=(19, "mm"), neck_height=(40, "mm"))
vol, area = pkg.get_volume_and_area() # extract volume and surface area
print("Volume (m³):", vol)
print("Surface Area (m²):", area)

📌 The examples show how to use either pkg or its properties to achieve mass transfer simulation for a specific geometry.

📌 To efficiently simulate the migration of substances from packaging materials, SFPPy unfolds complex 3D packaging geometries into an equivalent 1D representation. This transformation assumes that substance desorption is predominantly governed by diffusion within the walls of the packaging.

📌 The geometry.py module provides tools to compute surface-area-to-volume ratios, extract wall thicknesses, and generate equivalent 1D models for mass transfer simulations.

---

Snippet 4️⃣ | Using ⏩ as Mass Transfer Operator in Chained Simulations

📦 Click to expand

📌 SFPPy leverages multiple inheritance to define food contact conditions by combining storage conditions, food types, and physical properties.

📌 Additionally, three operators play a key role in SFPPy’s intuitive syntax:

• ➕ for combining layers and merging results
• ⏩ for naturally representing mass transfer
• % for introducing a new substance in the pipeline assessed

With these operators, mass transfer can be abstracted into a simple, visual representation:

1. 🍏⏩🍎
   (Direct transfer from green to red, symbolizing migration.)

2. 🍏⏩🟠⏩🍎
   (Includes an intermediate step, depicting progressive migration.)

3. 🍏⏩🟡⏩🟠⏩🍎
   (More detailed, illustrating multiple contamination stages over time.)

4. ⌬%🍏⏩🍎
   (Emphasizes new substance.)

🌟 SFPPy makes this abstraction possible with simple, expressive code.

from patankar.layer import gPET, PP
from patankar.food import ambient, hotfilled, realfood, fat, liquid, stacked
from patankar.loadpubchem import migrant

# Define migrant and packaging layers (ABA: PET-PP-PET)
m = migrant("limonene")
m2 = migrant("toluene") # alternative substance
A = gPET(l=(20, "um"), migrant=m, C0=0)
B = PP(l=(500, "um"), migrant=m, C0=200)  
ABA = A + B + A  # the most left layer is contact (food on the left)

# Define storage and processing conditions:
# 1:storage in stacks >> 2:hot-filled container >> 3:long-term storage of packaged food
class contact1(stacked, ambient): name = "1:setoff"; contacttime = (4, "months")
class contact2(hotfilled, realfood, liquid, fat): name = "2:hotfilling"
class contact3(ambient, realfood, liquid, fat): name = "3:storage"; contacttime = (6, "months")

# Instantiate and simulate with ⏩
medium1, medium2, medium3 = contact1(), contact2(), contact3()
m2 % medium1 >> ABA >> medium1 >> medium2 >> medium3  # Automatic chaining with m2 replacing m

# Merge all kinetics into a single one and plot the migration kinetics
sol123 = medium1.lastsimulation + medium2.lastsimulation + medium3.lastsimulation
sol123.plotCF()

🧩 How It Works

Each contact class inherits attributes from multiple base classes, allowing flexible combinations of:

1. 📌 Storage Conditions:

   • ambient: Defines standard storage at room temperature
   • hotfilled: Represents high-temperature filling processes
   • stacked: Models setoff migration when packaging layers are stacked

2. 🥘 Food Types & Interactions:

   • realfood: Represents actual food matrices
   • liquid: Specifies that the food is a liquid
   • fat: Indicates a fatty food, influencing partitioning behavior

📌 By combining classes, SFPPy allows streamlined, physics-based simulations with minimal code and facilitates the global understanding of the framework by AI.

---

Snippet 5️⃣ | Parameter linking 🔗 via layerLink

📦 Click to expand

# Any numeric property can be attached to a simulation with layerLink
from patankar.layer import layerLink
# Attach a variable function barrier thickness to ABA
fb_thickness = layerLink("l",indices=0) # index 0 = layer 1 (A) in contact with F
# Reuse ABA from Snippet 3 [...]
ABA.llink = fb_thicknesses
# Change dynamically the simulation by changing fb_thicknesses[0]
fb_thicknesses[0] = 12e-6 # 12 µm
medium1.lastsimulation.rerun()
# [...]

📌 Dynamic parameter binding using layerLink connections allows:

✅ Dynamic updates of $D$, $k$, $l$, $C_0$ abd $T$ for specific layers only ( index [i] refers to the layer i+1).
✅ Seamless integration of simulation and optimization tasks.
✅ Robust handling of parameter uncertainties in complex simulation scenarios.

---

📖 Case Studies

The project includes four detailed examples (example1.py, example2.py, example3.py, and example4.py), showcasing real-world scenarios with various materials, substances, food types, geometries, and usage conditions.

Example 1: | Mass Transfer from ♶ Monolayer Materials

• 🥪 Simulates the migration of Irganox 1076 and Irgafos 168 from a 100 µm LDPEfilm into a fatty sandwich 🥖over 10 days at 7°C.
• 📈 Evaluates migration kinetics and their implications for food safety.

---

Example 2| Mass Transfer in ♻️ Recycled PP Bottles

• 🍼 Investigates toluene migration from a 300 µm thick recycled PP bottle into a fatty liquid food.
• 🛡️ Assesses the effect of a PET functional barrier (FB) of varying thickness on reducing migration.

---

Example 3 | Advanced Migration Simulation ⛓️ with Variants

• 📦 Simulates migration in a trilayer (ABA) multilayer system, with PET (A) and recycled PP (B).
• 🔥 Evaluates migration behavior across storage with set-off, hot-filling, and long-term storage conditions.
• ⚙️ Explores variants where the migrant and layer thickness are modified to assess performance.
• 🍏⏩🍎 Example 3 showcases the mass transfer operator ⏩.

---

Example 4 | Parameter Fitting and Optimization ⚙️

• ✅ Fit diffusivities ($D$) and partitioning coefficients ($\frac{k}{k_0}$) from migration kinetic data 📈.
• ✅ Utilize dynamic parameter linking 🔗🧲 with layerLink.
• ✅ Integrate simulation results directly with experiments for sensitivity analysis and optimization

---

Caution

These examples do not discuss sources of uncertainty. Please refer to our publications and this link for details on the limitations of the presented approaches and assumptions.

🌟 Why SFPPy?

✔️ Free & Open Source — No licensing, no lock-in. Use it, adapt it, share it.

✔️ AI-Ready Design — Symbolic, structured data and a clean Python API make it ideal for integration with AI assistants and LLMs.

✔️ Chemically-oriented — SFPPy is designed to use chemical information and molecular models without requiring you to estimate diffusion and partitioning properties. The connection with PubChem server extends theoretically the possibilities to any single substance.

✔️ Chemical databases — Parsed US (🇺🇸), EU (🇪🇺), and GB (🇨🇳) databases are included in SFPPy and open source.

✔️ Flexible Unit Handling — Supports any unit via ("unit", value) or (["val1", "val2"], "unit") formats.

✔️ Chained Operators — Use >> to model automatic mass transfer and property propagation across layers and conditions. A same calculation pipe can be instantiated with different substances using the operator %: substance % food << geometry >> packaging >> step1 >> step2 >> step3...

✔️ Minimal Code, Maximum Expressiveness — Concise syntax using + to combine materials, simulate stacks, or switch storage scenarios. Combine also results with +: allsteps = step1.lastsimulation+step2.lastsimulation+step3.lastsimulation

✔️ Powerful Abstractions — Integrates with PubChem, ToxTree, built-in polymer libraries, and 3D packaging geometries.

✔️ Built-in Visualization & Export — Export results to Excel (.xlsx), CSV, PDF, PNG, and even MATLAB (if you must 😉).

✔️ Compliance Notebooks Included — Templates and real-case notebooks guide you through regulatory testing and reporting.

✔️ GUI-Ready Components — Build your own graphical tools using included widgets and high-level interfaces.

---

📜 License

MIT License

---

🤝 Contributors

INRAE - Olivier Vitrac
This project is part of the SFPPy initiative, aiming to bring the SafeFoodPackaging Portal version 3 (SFPP3) to the general public.

$2025-02-12$

---

For further details, consult the online documentation and the release page for new capabilities.

---

🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️
🍽️🍽️🍎🍎🍎🍎🍽️🍽️🍎🍎🍎🍎🍎🍽️🍽️🍏🍏🍏🍏🍽️🍽️🍽️🍎🍎🍎🍎🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️
🍽️🍎🍽️🍽️🍽️🍽️🍽️🍽️🍎🍽️🍽️🍽️🍽️🍽️🍽️🍏🍽️🍽️🍽️🍏🍽️🍽️🍎🍽️🍽️🍽️🍎🍽️🍽️🐍🍽️🍽️🍽️🐍🍽️
🍽️🍽️🍎🍎🍎🍽️🍽️🍽️🍎🍎🍎🍎🍽️🍽️🍽️🍏🍏🍏🍏🍽️🍽️🍽️🍎🍎🍎🍎🍽️🍽️🍽️🍽️🐍🍽️🐍🍽️🍽️
🍽️🍽️🍽️🍽️🍽️🍎🍽️🍽️🍎🍽️🍽️🍽️🍽️🍽️🍽️🍏🍽️🍽️🍽️🍽️🍽️🍽️🍎🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🐍🍽️🍽️🍽️
🍽️🍎🍎🍎🍎🍽️🍽️🍽️🍎🍽️🍽️🍽️🍽️🍽️🍽️🍏🍽️🍽️🍽️🍽️🍽️🍽️🍎🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🐍🍽️🍽️🍽️
🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️🍽️ $v1.41$

---

Important

is a lightweight, browser-based sister project of SFPPy. It runs entirely in your browser (via JupyterLite) — no installation, no Python backend — and is ideal for editing files, exploring materials, or performing basic compliance calculations on the go.

---

🍏⏩🍎 SFPPy: Built for AI. Ready for Simulation.

🤖 +⚖️ Can robots like GPT really evaluate food contact compliance using SFPPy? Check out the intriguing answers from two GPT-powered experts here!.

☝🏻Click on the image to learn more.

🔮Explore the future. Coding is a language—and with generative AI, we can bridge real-world problems to simulation-ready computer code. Python is the medium of choice, as it remains the most fluent language for AI systems. ╰┈➤Prompts accelerate simulation prototyping and the design of complex case scenarios. Thanks to the abstract nature of this interface, there are no constraints on the level of complexity: it operates independently of the underlying mathematical or numerical methods.

Credits: Olivier Vitrac

🤔With respect to regulatory compliance, AI assists you by generating informed scenarios and interpretations—but you remain the decision-maker.