jablonski 0.1.0__tar.gz

jablonski-0.1.0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: jablonski
+Version: 0.1.0
+Summary: Write and simulate ODE systems to describe the transitions in spectroscopic molecular systems.
+Keywords: 
+Author: Tomas Di Napoli, Hernan E. Grecco
+Author-email: Tomas Di Napoli <tomas.dina98@gmail.com>, Hernan E. Grecco <hernan.grecco@gmail.com>
+License-Expression: BSD-3-Clause
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Classifier: Programming Language :: Python :: 3
+Requires-Dist: poincare>=1.1.1
+Requires-Python: >=3.12
+Project-URL: homepage, https://github.com/dyscolab/jablonski
+Project-URL: issues, https://github.com/dyscolab/jablonski/issues
+Project-URL: documentation, https://dyscolab.github.io/jablonski

jablonski-0.1.0/pyproject.toml

@@ -0,0 +1,112 @@
+[project]
+name = "jablonski"
+authors = [
+  { name = "Tomas Di Napoli", email = "tomas.dina98@gmail.com" },
+  { name = "Hernan E. Grecco", email = "hernan.grecco@gmail.com" },
+]
+description = "Write and simulate ODE systems to describe the transitions in spectroscopic molecular systems."
+version = "0.1.0"
+requires-python = ">=3.12"
+keywords = []
+license = "BSD-3-Clause"
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python",
+  "Topic :: Software Development :: Libraries",
+  "Intended Audience :: Science/Research",
+  "Topic :: Scientific/Engineering",
+  "Programming Language :: Python :: 3",
+]
+dependencies = ["poincare >= 1.1.1"]
+
+[project.urls]
+homepage = "https://github.com/dyscolab/jablonski"
+issues = "https://github.com/dyscolab/jablonski/issues"
+documentation = "https://dyscolab.github.io/jablonski"
+
+[build-system]
+requires = ["uv_build>=0.9,<0.10"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+addopts = ["--import-mode=importlib"]
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.ruff.lint]
+extend-select = ["I"]
+
+[tool.pyright]
+typeCheckingMode = "standard"
+venv = "test"
+venvPath = ".pixi/envs/"
+
+[tool.pyrefly]
+python-interpreter-path = ".pixi/envs/default/bin/python"
+project-excludes = [".pixi", "**/__pycache__"]
+
+[tool.ty.environment]
+python = ".pixi/envs/default"
+
+[tool.pixi.workspace]
+channels = ["conda-forge"]
+platforms = ["linux-64", "osx-arm64", "win-64"]
+preview = ["pixi-build"]
+
+[tool.pixi.package.build]
+backend = { name = "pixi-build-python", version = "0.4.*" }
+config = { ignore-pypi-mapping = false }                    # Enable automatic PyPI-to-conda mapping
+
+[tool.pixi.package.host-dependencies]
+uv-build = "*"
+
+
+[tool.pixi.environments]
+default = ["test", "py312"]
+lint = { features = ["lint"], no-default-feature = true }
+build = { features = ["build"], no-default-feature = true }
+test-py312 = ["test", "py312"]
+test-py313 = ["test", "py313"]
+test-py314 = ["test", "py314"]
+
+[tool.pixi.dependencies]
+jablonski = { path = "." }
+
+[tool.pixi.feature.lint.dependencies]
+pre-commit = "*"
+pre-commit-hooks = "*"
+taplo = "*"
+ruff = "*"
+mdformat = "*"
+mdformat-ruff = "*"
+pyright = "*"
+
+[tool.pixi.feature.lint.tasks]
+pre-commit-install = "pre-commit install"
+lint = "pre-commit run"
+
+[tool.pixi.feature.build.dependencies]
+uv = "*"
+python = "*"
+
+
+[tool.pixi.feature.build.tasks]
+_build = "uv build"
+_publish = "uv publish"
+
+
+[tool.pixi.feature.test.dependencies]
+matplotlib = "*"
+pytest = "*"
+pooch = "*"
+
+[tool.pixi.feature.test.tasks]
+test = "pytest --doctest-modules"
+
+[tool.pixi.feature]
+py312.dependencies = { python = "3.12.*" }
+py313.dependencies = { python = "3.13.*" }
+py314.dependencies = { python = "3.14.*" }

jablonski-0.1.0/src/jablonski/__init__.py

@@ -0,0 +1,28 @@
+"""
+jablonski
+~~~~~~~~~
+
+Write and simulate ODE systems to describe the transitions in spectroscopic
+molecular systems.
+
+:copyright: 2024 by jablonski Authors, see AUTHORS for more details.
+:license: BSD, see LICENSE for more details.
+"""
+
+from poincare import Parameter, Simulator, assign
+
+from . import simulation, transitions, util
+from .states import SingletState, SpectroscopicSystem, TripletState, initial
+
+__all__ = [
+    "transitions",
+    "simulation",
+    "util",
+    "SpectroscopicSystem",
+    "initial",
+    "TripletState",
+    "SingletState",
+    "assign",
+    "Parameter",
+    "Simulator",
+]

jablonski-0.1.0/src/jablonski/_typing.py

@@ -0,0 +1,35 @@
+"""
+jablonski._typing
+~~~~~~~~~~~~~~~~~
+
+Types and type alias.
+
+:copyright: 2024 by jablonski Authors, see AUTHORS for more details.
+:license: BSD, see LICENSE for more details.
+"""
+
+from typing import Literal, Protocol, TypeAlias, runtime_checkable
+
+import pint
+from poincare import Parameter, Variable
+
+Power: TypeAlias = float | int
+Time: TypeAlias = float | int | pint.Quantity
+
+SpinMultiplicity = Literal["singlet", "triplet"]
+
+
+@runtime_checkable
+class Pumper(Protocol):
+    pump: Parameter
+
+
+@runtime_checkable
+class RadiativeDecay(Protocol):
+    radiative_decay: Parameter
+
+
+@runtime_checkable
+class Drawable(Protocol):
+    _source: Variable
+    _target: Variable

jablonski-0.1.0/src/jablonski/_units.py

@@ -0,0 +1,20 @@
+"""
+    jablonski._units
+    ~~~~~~~~~~~~~~~~
+
+    Units and dimensions.
+
+    :copyright: 2024 by jablonski Authors, see AUTHORS for more details.
+    :license: BSD, see LICENSE for more details.
+"""
+
+import pint
+
+ureg = pint.get_application_registry()
+
+DEFAULT_DELTA = 50 * ureg.picosecond
+
+DIM_WAVELENGTH = {"[length]": 1}
+DIM_WAVENUMBER = {"[length]": -1}
+DIM_FREQUENCY = {"[time]": -1}
+DIM_ENERGY = ureg.get_dimensionality("eV")

jablonski-0.1.0/src/jablonski/plots/jablonski_diagrams.py

@@ -0,0 +1,371 @@
+from itertools import chain
+from typing import Iterable, Literal, Mapping, NamedTuple
+
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
+
+Number = float | int
+column = str
+
+
+class Level(NamedTuple):
+    label: str
+    energy: Number
+    column: str
+    color: str = "black"
+    linewidth: Number = 2.5
+
+
+class Transition(NamedTuple):
+    source: Level
+    target: Level
+    radiative: bool
+    label: str | None = None
+    color: str = "royalblue"
+    linewidth: Number = 1
+
+
+class JablonskiDiagram:
+    def __init__(
+        self,
+        levels: Iterable[Level],
+        transitions: Iterable[Transition],
+        columns: Iterable[column] = ["singlet", "triplet"],
+    ):
+        self.levels = levels
+        self.transitions = transitions
+        self.columns = columns
+
+    def _place_columns(
+        self, columns: Iterable[column]
+    ) -> Mapping[column, tuple[Number, Number]]:
+        num_columns = len(columns)
+        # Spaces between levels are 1/4 level width, calculated automatically to use all of xscale
+        # level_lenght l is the solution to  n*l + (n-1)*l/4 = xscale, n = num_column
+        level_length = self._xscale / (5 / 4 * num_columns - 1 / 4)
+        interval_length = level_length / 4
+        column_positions = {
+            col: (
+                i * interval_length + i * level_length,
+                i * interval_length + (i + 1) * level_length,
+            )
+            for i, col in enumerate(columns)
+        }
+        return column_positions
+
+    def _build_positions(
+        self, column_positions: Mapping[column, tuple[Number, Number]]
+    ) -> Mapping[column, tuple[tuple[Number, Number], Number]]:
+
+        positions = {}
+        for level in self.levels:
+            positions[level] = (
+                column_positions[level.column],
+                level.energy,
+            )
+        return positions
+
+    def _sort_transitions(
+        self, column_positions: Mapping[column, tuple[Number, Number]]
+    ) -> tuple[
+        Mapping[column, Mapping[Literal["up", "down"], Iterable[Transition]]],
+        Mapping[column, Mapping[Literal["forward", "backward"], Iterable[Transition]]],
+    ]:
+        intracolumn_transitions = {
+            column: [
+                t
+                for t in self.transitions
+                if t.source.column == column and t.target.column == column
+            ]
+            for column in self.columns
+        }
+        multicolumn_transitions = {
+            column: [
+                t
+                for t in self.transitions
+                if t.source.column == column and t.source.column != t.target.column
+            ]
+            for column in self.columns
+        }
+        sorted_intracolumn_transitions = {
+            column: {
+                "up": sorted(
+                    [
+                        t
+                        for t in intracolumn_transitions[column]
+                        if t.target.energy >= t.source.energy
+                    ],
+                    key=lambda t: (t.source.energy, -t.target.energy),
+                ),
+                "down": sorted(
+                    [
+                        t
+                        for t in intracolumn_transitions[column]
+                        if t.target.energy < t.source.energy
+                    ],
+                    key=lambda t: (t.target.energy, -t.source.energy),
+                ),
+            }
+            for column in self.columns
+        }
+        sorted_multicolumn_transitions = {
+            column: {
+                "backward": [
+                    t
+                    for t in multicolumn_transitions[column]
+                    if column_positions[t.source.column][0]
+                    >= column_positions[t.target.column][0]
+                ],
+                "forward": [
+                    t
+                    for t in multicolumn_transitions[column]
+                    if column_positions[t.source.column][0]
+                    < column_positions[t.target.column][0]
+                ],
+            }
+            for column in self.columns
+        }
+        return sorted_intracolumn_transitions, sorted_multicolumn_transitions
+
+    def plot(
+        self,
+        figsize: tuple[Number, Number] = (
+            6.4,
+            4.8,
+        ),
+        fontsize: Number = 10,
+        show_energy_axis: bool = True,
+    ) -> tuple[Axes, Figure]:
+
+        # Use energy ranges and figure size
+        energies = [level.energy for level in self.levels]
+        max_energy = np.max(energies)
+        min_energy = np.min(energies)
+        self._yscale = max_energy - min_energy
+        self._xscale = self._yscale * figsize[0] / figsize[1]
+
+        column_positions = self._place_columns(self.columns)
+        positions = self._build_positions(column_positions)
+        intracolumn, multicolumn = self._sort_transitions(column_positions)
+
+        fig, ax = plt.subplots(figsize=figsize)
+
+        # Draw energy levels
+        for level, ((x_start, x_end), y) in positions.items():
+            ax.hlines(
+                y,
+                x_start,
+                x_end,
+                linewidth=level.linewidth,
+                color=level.color,
+            )
+
+            ax.text(
+                x_end + 0.015 * self._xscale,
+                y,
+                level.label,
+                va="center",
+                fontsize=fontsize,
+            )
+
+        # Draw  transitions
+        for column in self.columns:
+            x_start, x_end = column_positions[column]
+            n_intra = len(intracolumn[column]["up"]) + len(intracolumn[column]["down"])
+            spacing = (x_end - x_start) / (n_intra + 1)
+
+            # draw intracolumn transitions
+            for i, transition in enumerate(
+                chain(intracolumn[column]["up"], intracolumn[column]["down"])
+            ):
+                self._draw_transition(
+                    ax,
+                    (
+                        x_start + (i + 1) * spacing,
+                        transition.source.energy,
+                    ),
+                    (
+                        x_start + (i + 1) * spacing,
+                        transition.target.energy,
+                    ),
+                    label=transition.label,
+                    radiative=transition.radiative,
+                    color=transition.color,
+                    linewidth=transition.linewidth,
+                )
+            for transition in multicolumn[column]["backward"]:
+                self._draw_transition(
+                    ax,
+                    (x_start, transition.source.energy),
+                    (
+                        column_positions[transition.target.column][1],
+                        transition.target.energy,
+                    ),
+                    label=transition.label,
+                    radiative=transition.radiative,
+                    color=transition.color,
+                    linewidth=transition.linewidth,
+                )
+            for transition in multicolumn[column]["forward"]:
+                self._draw_transition(
+                    ax,
+                    (x_end, transition.source.energy),
+                    (
+                        column_positions[transition.target.column][0],
+                        transition.target.energy,
+                    ),
+                    label=transition.label,
+                    radiative=transition.radiative,
+                    color=transition.color,
+                    linewidth=transition.linewidth,
+                )
+
+        # Formatting
+        ax.set_xlim(-0.05 * self._xscale, self._xscale * 1.1)
+        ax.set_xticks([])
+
+        ax.set_ylim(
+            min_energy - self._yscale * 0.05,
+            max_energy + self._yscale * 0.05,
+        )
+
+        ax.xaxis.set_visible(False)
+
+        if show_energy_axis:
+            ax.set_ylabel("Energy")
+            ax.set_yticks(energies)
+        else:
+            ax.set_yticks([])
+
+        fig.tight_layout()
+        return fig, ax
+
+    def _draw_transition(
+        self,
+        ax: Axes,
+        start: tuple[Number, Number],
+        end: tuple[Number, Number],
+        label: str | None,
+        radiative: bool,
+        color="royalblue",
+        linewidth: Number = 1,
+    ):
+        x1, y1 = start
+        x2, y2 = end
+
+        if radiative:
+            ax.annotate(
+                "",
+                xy=(x2, y2),
+                xytext=(x1, y1),
+                arrowprops=dict(
+                    arrowstyle="->",
+                    linestyle="-",
+                    color=color,
+                    lw=linewidth,
+                ),
+            )
+
+        else:
+            # "Squiggly" lines are a straight line with a pieceswise modulation: 1. sine wave, 2: interpolating spline, 3: straight line.
+            dx = x2 - x1
+            dy = y2 - y1
+            length = np.hypot(dx, dy)
+
+            if length == 0:
+                return
+
+            px = -dy / length
+            py = dx / length
+            amplitude = 0.01 * (self._xscale * np.abs(px) + self._yscale * np.abs(py))
+            frequency = 12
+
+            # Define the time splits (t goes from 0 to 1)
+            t1 = 0.85  # Spline start
+            t2 = 0.90  # Straight line start
+
+            t_sine = np.linspace(0, t1, 200)
+            wiggle_sine = amplitude * np.sin(2 * np.pi * frequency * t_sine)
+
+            # Boundary conditions for spline
+            w1 = amplitude * np.sin(2 * np.pi * frequency * t1)
+            dw1_dt = (
+                amplitude * (2 * np.pi * frequency) * np.cos(2 * np.pi * frequency * t1)
+            )
+
+            # Calculate spline
+            t_blend = np.linspace(t1, t2, 50)
+            u = (t_blend - t1) / (t2 - t1)
+
+            c0 = w1
+            c1 = dw1_dt * (t2 - t1)
+            c2 = -3 * c0 - 2 * c1
+            c3 = 2 * c0 + c1
+            wiggle_blend = c0 + c1 * u + c2 * u**2 + c3 * u**3
+
+            # Straight line
+            t_straight = np.linspace(t2, 1.0, 50)
+            wiggle_straight = np.zeros_like(t_straight)
+
+            t_all = np.concatenate([t_sine, t_blend[1:], t_straight[1:]])
+            wiggle_all = np.concatenate(
+                [wiggle_sine, wiggle_blend[1:], wiggle_straight[1:]]
+            )
+
+            x_wiggle = x1 + dx * t_all + px * wiggle_all
+            y_wiggle = y1 + dy * t_all + py * wiggle_all
+
+            ax.plot(
+                x_wiggle,
+                y_wiggle,
+                color=color,
+                lw=linewidth,
+            )
+
+            # Arrow head
+            ax.annotate(
+                "",
+                xy=(x_wiggle[-1], y_wiggle[-1]),
+                xytext=(x_wiggle[-5], y_wiggle[-5]),
+                arrowprops=dict(
+                    arrowstyle="->",
+                    color=color,
+                    lw=linewidth,
+                ),
+            )
+
+            ax.plot(
+                x_wiggle,
+                y_wiggle,
+                color=color,
+                lw=linewidth,
+            )
+
+            # Arrow head (now perfectly tracking the final straight segment)
+            ax.annotate(
+                "",
+                xy=(x_wiggle[-1], y_wiggle[-1]),
+                xytext=(x_wiggle[-5], y_wiggle[-5]),
+                arrowprops=dict(
+                    arrowstyle="->",
+                    color=color,
+                    lw=linewidth,
+                ),
+            )
+        if label:
+            xm = (x1 + x2) / 2
+            ym = (y1 + y2) / 2
+            ax.text(
+                xm,
+                ym,
+                label,
+                fontsize=10,
+                color=color,
+                bbox=dict(
+                    facecolor="white",
+                    edgecolor="none",
+                    alpha=0.7,
+                ),
+            )