photosurfactant 1.0.0__tar.gz

photosurfactant-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,31 @@
+name: "Publish"
+
+on:
+  push:
+    tags:
+      # Publish on any tag starting with a `v`, e.g., v0.1.0
+      - v*
+
+jobs:
+  run:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Install Python 3.13
+        run: uv python install 3.13
+
+      - name: Build
+        run: uv build
+
+      - name: Publish
+        run: uv publish

photosurfactant-1.0.0/.github/workflows/pytest.yml

@@ -0,0 +1,69 @@
+name: CI
+
+on:
+  # Trigger the workflow on push to main or dev, except tag creation
+  push:
+    branches:
+      - 'main'
+      - 'dev'
+  # Trigger the workflow on pull request
+  pull_request: ~
+  # Trigger the workflow manually
+  workflow_dispatch: ~
+  # Trigger after public PR approved for CI
+  pull_request_target:
+    types: [labeled]
+  release:
+    types: [created]
+
+jobs:
+  qa:
+    name: qa
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "0.7.3"
+
+      - name: Install Python
+        run: uv python install
+
+      - name: Install the project
+        run: uv sync --locked --all-extras --dev
+
+      - name: Check isort
+        run: uvx ruff check --select I .
+
+      - name: Check formatting
+        run: uvx ruff format --diff .
+
+      - name: Check linting
+        run: uvx ruff check .
+
+  pytest:
+    name: pytest
+    needs: qa
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "0.7.3"
+
+      - name: Install Python
+        run: uv python install
+
+      - name: Install the project
+        run: uv sync --dev
+
+      - name: Run tests
+        run: uv run pytest tests

photosurfactant-1.0.0/.gitignore

@@ -0,0 +1,175 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+.python-version
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+m4r_venv/
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Figures and data
+figures/
+data/
+
+# Mac stuff
+.DS_Store
+
+# IDEA
+.idea/
+
+# Lock files
+# uv.lock

photosurfactant-1.0.0/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: photosurfactant
+Version: 1.0.0
+Summary: Models of chromocapillary flows for photo-actuated liquid mixing and sculpting.
+Author-email: Niall Oswald <niall.oswald20@imperial.ac.uk>
+Requires-Python: >=3.12
+Requires-Dist: alive-progress>=3.3.0
+Requires-Dist: matplotlib>=3.10.7
+Requires-Dist: numpy>=2.3.4
+Requires-Dist: scipy>=1.16.2
+Description-Content-Type: text/markdown
+
+# Photosurfactant
+
+[![DOI](https://zenodo.org/badge/734330906.svg)](https://zenodo.org/badge/latestdoi/734330906)
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/NiallOswald/photosurfactant/pytest.yml?label=tests)
+![PyPI - Version](https://img.shields.io/pypi/v/photosurfactant)
+
+Numerical solvers for liquid mixing and sculpting using light-actuated photosurfactants.
+
+# Publications
+
+This package has been used in the following publications:
+
+- (Submitted) M. D. Mayer, N. J. Oswald, D. T. Papageorgiou, 2026. Liquid mixing and sculpting using light-actuated photosurfactants.

photosurfactant-1.0.0/README.md

@@ -0,0 +1,13 @@
+# Photosurfactant
+
+[![DOI](https://zenodo.org/badge/734330906.svg)](https://zenodo.org/badge/latestdoi/734330906)
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/NiallOswald/photosurfactant/pytest.yml?label=tests)
+![PyPI - Version](https://img.shields.io/pypi/v/photosurfactant)
+
+Numerical solvers for liquid mixing and sculpting using light-actuated photosurfactants.
+
+# Publications
+
+This package has been used in the following publications:
+
+- (Submitted) M. D. Mayer, N. J. Oswald, D. T. Papageorgiou, 2026. Liquid mixing and sculpting using light-actuated photosurfactants.

photosurfactant-1.0.0/examples/slip-velocity.py

@@ -0,0 +1,36 @@
+import matplotlib.pyplot as plt
+import numpy as np
+
+from photosurfactant import Parameters
+from photosurfactant.fourier import fourier_series_coeff
+from photosurfactant.semi_analytic import (
+    FirstOrder,
+    LeadingOrder,
+    Variables,
+)
+
+params = Parameters()
+leading = LeadingOrder(params)
+
+# Find the Fourier series of the slip velocity
+wavenumbers, func_coeffs = fourier_series_coeff(
+    lambda x: 1e-3 * np.sin(2 * np.pi * x / params.L), params.L, 10
+)
+
+# Solve the first-order problem by fixing u(x, 1) = f(x)
+first = FirstOrder(wavenumbers, params, leading)
+first.solve(
+    lambda n: (
+        (first._psi(wavenumbers[n], 1, z_order=1), func_coeffs[n])
+        if n > 0
+        else (Variables.f, 0)
+    )  # There is no flow at n = 0, so we fix the light intensity instead
+)
+
+# Evaluate and plot the light intensity profile
+xx = np.linspace(-params.L, params.L, 100)
+
+plt.plot(xx, first.f(xx))
+plt.xlabel("$x$")
+plt.ylabel("$f(x)$")
+plt.show()

photosurfactant-1.0.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "photosurfactant"
+version = "1.0.0"
+description = "Models of chromocapillary flows for photo-actuated liquid mixing and sculpting."
+readme = "README.md"
+authors = [
+    { name = "Niall Oswald", email = "niall.oswald20@imperial.ac.uk" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "alive-progress>=3.3.0",
+    "matplotlib>=3.10.7",
+    "numpy>=2.3.4",
+    "scipy>=1.16.2",
+]
+
+[project.scripts]
+plot_error = "photosurfactant.scripts.plot_error:plot_error"
+plot_first_order = "photosurfactant.scripts.plot_first_order:plot_first_order"
+plot_leading_order = "photosurfactant.scripts.plot_leading_order:plot_leading_order"
+plot_spectrum = "photosurfactant.scripts.plot_spectrum:plot_spectrum"
+plot_sweep = "photosurfactant.scripts.plot_sweep:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4.2",
+    "pytest-cases>=3.9.1",
+    "scipy-stubs>=1.16.3.0",
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["photosurfactant"]

photosurfactant-1.0.0/src/photosurfactant/__init__.py

@@ -0,0 +1 @@
+from .parameters import Parameters as Parameters

photosurfactant-1.0.0/src/photosurfactant/fourier.py

@@ -0,0 +1,47 @@
+"""Module for Fourier series calculations."""
+
+import numpy as np
+import numpy.typing as npt
+
+
+def fourier_series_coeff(func, L: float, N: int) -> npt.NDArray[np.complex128]:
+    """Calculate the first N+1 Fourier series coeff. of a periodic function.
+
+    Given a periodic function f(x) with period 2L, this function returns the
+    coefficients {c0,c1,c2,...} such that:
+
+    f(x) ~= sum_{k=-N}^{N} c_k * exp(i*2*pi*k*x/L)
+
+    where we define c_{-n} = complex_conjugate(c_{n}).
+
+    :param func: The periodic function, a callable like f(x).
+    :param L: Half the period of the function f, so that f(-L)==f(L).
+    :param N: The function will return the first N + 1 Fourier coeff.
+    """
+    xx = np.linspace(-L, L, 2 * N, endpoint=False)
+    f_coeffs = np.fft.rfft(np.array([func(x) for x in xx])) / len(xx)
+    f_coeffs *= np.exp(1.0j * np.pi * np.arange(N + 1))  # Shift frequency domain
+
+    return np.arange(0, N + 1) * np.pi / L, f_coeffs
+
+
+def convolution_coeff(f, g, L: float, N: int):
+    """Calculate the first N+1 Fourier series coeff. of a convolution.
+
+    Given periodic functions f(x), g(x) with period 2L, this function returns the
+    coefficients {c0,c1,c2,...} such that:
+
+    f(x) * g(x) ~= sum_{k=-N}^{N} c_k * exp(i*2*pi*k*x/L)
+
+    where we define c_{-n} = complex_conjugate(c_{n}).
+
+    :param f: A periodic function, a callable like f(x).
+    :param g: A periodic function, a callable like f(x).
+    :param L: Half the period of the function f, so that f(-L)==f(L).
+    :param N: The function will return the first 2N + 1 Fourier coeff.
+    """
+    omega, f_full = fourier_series_coeff(f, L, N)
+    _, g_full = fourier_series_coeff(g, L, N)
+    f_conv_full = 2 * L * f_full * g_full
+
+    return omega, f_conv_full

photosurfactant-1.0.0/src/photosurfactant/intensity_functions.py

@@ -0,0 +1,32 @@
+"""Example light intensity and surface perturbations."""
+
+from typing import Callable
+
+import numpy as np
+import scipy as sp
+
+
+def gaussian(x: float, d=1.0) -> float:
+    return super_gaussian(x, 2.0, d)
+
+
+def super_gaussian(x: float, k: float, d=1.0) -> float:
+    return np.exp(-(abs(x / d) ** k))
+
+
+def square_wave(x: float) -> float:
+    return float(abs(x) < 1)
+
+
+def smoothed_square(x: float, delta: float) -> float:
+    return 0.5 * (np.tanh((x + 1) / delta) - np.tanh((x - 1) / delta))
+
+
+def mollifier(delta: float) -> Callable[[float], float]:
+    def _(x):
+        if abs(x) < delta:
+            return np.exp(-(delta**2) / (delta**2 - x**2))
+        else:
+            return 0.0
+
+    return lambda x: _(x) / sp.integrate.quad(_, -1.0, 1.0)[0]

photosurfactant-1.0.0/src/photosurfactant/parameters.py

@@ -0,0 +1,219 @@
+"""A module for the Parameters class."""
+
+import inspect
+from copy import copy
+from dataclasses import asdict, dataclass
+from typing import Any
+
+import numpy as np
+
+
+@dataclass(frozen=True)
+class Parameters:
+    """The Parameters for the model.
+
+    :param L: The aspect ratio of the domain.
+    :param Da_tr: The Damkohler number for the trans surfactant.
+    :param Da_ci: The Damkohler number for the cis surfactant.
+    :param Pe_tr: The Peclet number for the trans surfactant.
+    :param Pe_ci: The Peclet number for the cis surfactant.
+    :param Pe_tr_s: The Peclet number for the trans surfactant on the
+        interface.
+    :param Pe_ci_s: The Peclet number for the cis surfactant on the interface.
+    :param Bi_tr: The Biot number for the trans surfactant.
+    :param Bi_ci: The Biot number for the cis surfactant.
+    :param Ma: The Marangoni number.
+    :param k_tr: The adsorption rate for the trans surfactant.
+    :param k_ci: The adsorption rate for the cis surfactant.
+    :param chi_tr: The desorption rate for the trans surfactant.
+    :param chi_ci: The desorption rate for the cis surfactant.
+    """
+
+    # Aspect ratio
+    L: float = 10.0
+
+    # Reynolds numbers
+    Re: float = 0.0  # TODO: Deprecate this parameter
+
+    # Damkohler numbers
+    Da_tr: float = 1.0
+    Da_ci: float = 2.0
+
+    # Peclet numbers
+    Pe_tr: float = 10.0
+    Pe_ci: float = 10.0
+
+    # Interfacial Peclet numbers
+    Pe_tr_s: float = 10.0
+    Pe_ci_s: float = 10.0
+
+    # Biot numbers
+    Bi_tr: float = 1 / 300
+    Bi_ci: float = 1.0
+
+    # Marangoni number
+    Ma: float = 2.0
+
+    # Adsorption and desorption rates
+    k_tr: float = 1.0
+    k_ci: float = 1 / 30
+
+    chi_tr: float = 100 / 30
+    chi_ci: float = 100.0
+
+    def __post_init__(self):  # noqa: D105
+        if not np.isclose(self.k_tr * self.chi_tr, self.k_ci * self.chi_ci):
+            raise ValueError(
+                "Adsorption rates do not satisfy the condition k * chi = const."
+            )
+
+    def from_dict(kwargs: dict[str, float]) -> "Parameters":
+        """Load parameters from a dictionary."""
+        return Parameters(
+            **{
+                k: v
+                for k, v in kwargs.items()
+                if k in inspect.signature(Parameters).parameters
+            }
+        )
+
+    def copy(self) -> "Parameters":
+        """Return a copy of the `Parameters` object."""
+        return copy(self)
+
+    def update(self, **new_kwargs) -> "Parameters":
+        """Return a new `Parameter` object with missing values derived."""
+        derived_kwargs = asdict(self)
+        # new_kwargs overwrite derived_kwargs
+        return Parameters(**(derived_kwargs | new_kwargs))
+
+    @property
+    def alpha(self) -> float:
+        return self.Da_ci / self.Da_tr
+
+    @property
+    def eta(self) -> float:
+        return self.Pe_tr / self.Pe_ci
+
+    @property
+    def zeta(self) -> float:
+        return self.Pe_tr * self.Da_tr + self.Pe_ci * self.Da_ci
+
+    @property
+    def P(self):
+        return np.array([[self.Pe_tr, 0.0], [0.0, self.Pe_ci]])
+
+    @property
+    def P_s(self):
+        return np.array([[self.Pe_tr_s, 0.0], [0.0, self.Pe_ci_s]])
+
+    @property
+    def B(self):
+        return np.array([[self.Bi_tr, 0.0], [0.0, self.Bi_ci]])
+
+    @property
+    def K(self):
+        return np.array([[self.k_tr, 0.0], [0.0, self.k_ci]])
+
+    @property
+    def A(self):
+        return self.P @ self._D
+
+    @property
+    def A_s(self):
+        return self.P_s @ self._D
+
+    @property
+    def V(self):
+        return np.array([[self.alpha, self.eta], [1.0, -1.0]])
+
+    @property
+    def Lambda(self):
+        return np.array([[0.0, 0.0], [0.0, self.zeta]])
+
+    @property
+    def _D(self):
+        return np.array([[self.Da_tr, -self.Da_ci], [-self.Da_tr, self.Da_ci]])
+
+
+@dataclass
+class PlottingParameters:
+    """Additional parameters for plotting.
+
+    :param wave_count: The number of wave numbers to use.
+    :param grid_size: The number of grid points to evaluate the solution on.
+    :param mollify: A flag to mollify the input function.
+    :param delta: The mollification parameter.
+    :param norm_scale: Normalization type. Either "linear" or "log".
+    :param save: A flag to save the figures to disk.
+    :param path: The path to save the figures to.
+    :param label: A label to append to the figure filenames.
+    :param format: The format to save the figures in.
+    """
+
+    wave_count: int = 100
+    grid_size: int = 1000
+    mollify: bool = False
+    delta: float = 0.5
+    norm_scale: str = "linear"
+    save: bool = False
+    path: str = "./"
+    label: str = ""
+    usetex: bool = False
+    format: str = "png"
+
+    def __post_init__(self):  # noqa: D105
+        self.label = "_" + self.label if self.label else ""
+        self.plot_setup()
+
+    def from_dict(kwargs: dict[str, Any]) -> "PlottingParameters":
+        """Load parameters from a dictionary."""
+        return PlottingParameters(
+            **{
+                k: v
+                for k, v in kwargs.items()
+                if k in inspect.signature(PlottingParameters).parameters
+            }
+        )
+
+    def copy(self):
+        """Return a copy of the class."""
+        raise NotImplementedError
+        # TODO: Deprecate this method
+        return copy(self)
+
+    def plot_setup(self):
+        """Set up the matplotlib rcParams."""
+        import matplotlib.pyplot as plt
+
+        rcparams = {
+            "font.size": 18,
+            "axes.labelsize": 18,
+            "axes.titlesize": 18,
+            "axes.formatter.useoffset": True,
+            "xtick.labelsize": 16,
+            "ytick.labelsize": 16,
+            "legend.fontsize": 16,
+            "figure.figsize": [7, 6],
+            "figure.dpi": 100,
+            "figure.autolayout": True,
+            "savefig.dpi": 300,
+        }
+
+        if self.usetex:
+            plt.rcParams.update(
+                {
+                    "text.usetex": True,
+                    "font.family": "serif",
+                    "font.serif": ["Computer Modern Roman"],
+                    "axes.formatter.use_mathtext": True,
+                    "text.latex.preamble": r"\usepackage{amsmath}",
+                }
+                | rcparams
+            )
+
+        else:
+            plt.rcParams.update(rcparams)
+
+        plt.close("all")
+        self.plt = plt