PyAntiGen 1.0.9__py3-none-any.whl

framework/data_interpolation.py

@@ -0,0 +1,340 @@
+"""
+Generate an Antimony piecewise function with linear or spline interpolation.
+
+This script takes vectors of times and values and generates an Antimony
+piecewise function that performs either linear or cubic spline interpolation 
+between the points.
+"""
+
+import numpy as np
+from typing import List, Union
+from scipy.interpolate import CubicSpline, PchipInterpolator
+
+
+def format_number(num: float, precision: int = 15) -> str:
+    """
+    Format a number for Antimony output, removing unnecessary trailing zeros.
+    
+    Parameters
+    ----------
+    num : float
+        Number to format
+    precision : int
+        Maximum number of decimal places (default: 15)
+    
+    Returns
+    -------
+    str
+        Formatted number string
+    """
+    # Use g format to remove trailing zeros, but limit precision
+    formatted = f"{num:.{precision}g}"
+    # Remove trailing decimal point if present
+    if formatted.endswith('.'):
+        formatted = formatted[:-1]
+    return formatted
+
+
+def _generate_linear_piecewise(
+    times: Union[List[float], np.ndarray],
+    data: Union[List[float], np.ndarray],
+    data_name: str = "data",
+    time_var: str = "time",
+    default_before: Union[float, str] = 0.0,
+    default_after: Union[float, str, None] = None
+) -> str:
+    """
+    Helper function to generate an Antimony piecewise function with linear interpolation.
+    """
+    times = np.array(times)
+    data = np.array(data)
+    
+    # Validate inputs
+    if len(times) != len(data):
+        raise ValueError("times and data must have the same length")
+    if len(times) < 2:
+        raise ValueError("At least 2 points are required for interpolation")
+    
+    # Sort by time to ensure proper ordering
+    sort_idx = np.argsort(times)
+    times = times[sort_idx]
+    data = data[sort_idx]
+    
+    # Set default to the last data value for times after the last point
+    if default_after is None:
+        default_after = data[-1]
+    
+    # Build piecewise conditions and expressions
+    pieces = []
+    
+    # Handle times before first point
+    pieces.append(str(default_before) if isinstance(default_before, str) else format_number(default_before))
+    pieces.append(f"{time_var} < {format_number(times[0])}")
+    
+    # Generate linear interpolation for each interval
+    for i in range(len(times) - 1):
+        t_i = times[i]
+        t_next = times[i + 1]
+        v_i = data[i]
+        v_next = data[i + 1]
+        
+        # Skip if times are equal (would cause division by zero)
+        if abs(t_next - t_i) < 1e-10:
+            continue
+        
+        # Linear interpolation formula: v = v_i + (v_next - v_i) * (t - t_i) / (t_next - t_i)
+        # For Antimony, we'll use: (v_i + (v_next - v_i) * (time_var - t_i) / (t_next - t_i))
+        
+        # Build the interpolation expression
+        if abs(v_next - v_i) < 1e-10:
+            # Constant value (no interpolation needed)
+            interp_expr = format_number(v_i)
+        else:
+            # Linear interpolation: v_i + slope * (time_var - t_i) / dt
+            slope = v_next - v_i
+            dt = t_next - t_i
+            v_i_str = format_number(v_i)
+            slope_str = format_number(slope)
+            t_i_str = format_number(t_i)
+            dt_str = format_number(dt)
+            interp_expr = f"({v_i_str} + ({slope_str} * ({time_var} - {t_i_str})) / {dt_str})"
+        
+        pieces.append(interp_expr)
+        pieces.append(f"{time_var} < {format_number(t_next)}")
+    
+    # Handle times after last point
+    pieces.append(str(default_after) if isinstance(default_after, str) else format_number(default_after))
+    pieces.append(f"{time_var} >= {format_number(times[-1])}")
+    
+    # Join pieces into Antimony piecewise function
+    piecewise_str = ", ".join(pieces)
+    result = f"{data_name} := piecewise({piecewise_str})"
+    
+    return result
+
+def _generate_linear_piecewise_symbolic(
+    times: List[str],
+    data: List[str],
+    data_name: str = "data",
+    time_var: str = "time",
+    default_before: str = "0.0",
+    default_after: Union[str, None] = None
+) -> str:
+    """
+    Helper function to generate an Antimony piecewise function with linear interpolation
+    using symbolic data values and symbolic times (strings).
+    """
+    # Validate inputs
+    if len(times) != len(data):
+        raise ValueError("times and data must have the same length")
+    if len(times) < 2:
+        raise ValueError("At least 2 points are required for interpolation")
+    
+    # Set default to the last data value for times after the last point
+    if default_after is None:
+        default_after = data[-1]
+    
+    # Build piecewise conditions and expressions
+    pieces = []
+    
+    times_str = [str(t) for t in times]
+    
+    # Handle times before first point
+    pieces.append(str(default_before))
+    pieces.append(f"{time_var} < {times_str[0]}")
+    
+    # Generate linear interpolation for each interval
+    for i in range(len(times_str) - 1):
+        t_i_str = times_str[i]
+        t_next_str = times_str[i + 1]
+        v_i_str = str(data[i])
+        v_next_str = str(data[i + 1])
+        
+        # Skip if times represent the exact same symbolic name
+        if t_next_str == t_i_str:
+            continue
+        
+        # Linear interpolation formula
+        dt_str = f"({t_next_str} - {t_i_str})"
+        interp_expr = f"({v_i_str} + ({v_next_str} - ({v_i_str})) * ({time_var} - {t_i_str}) / {dt_str})"
+        
+        pieces.append(interp_expr)
+        pieces.append(f"{time_var} < {t_next_str}")
+    
+    # Handle times after last point
+    pieces.append(str(default_after))
+    pieces.append(f"{time_var} > {times_str[-1]}")
+    
+    # Join pieces into Antimony piecewise function
+    piecewise_str = ", ".join(pieces)
+    result = f"{data_name} := piecewise({piecewise_str})"
+    
+    return result
+
+
+def _generate_spline_piecewise(
+    times: Union[List[float], np.ndarray],
+    data: Union[List[float], np.ndarray],
+    data_name: str = "data",
+    time_var: str = "time",
+    antimony_continuation: bool = True,
+    monotone: bool = False
+) -> str:
+    """
+    Helper function to generate an Antimony piecewise function with spline interpolation.
+    MIT License
+
+    Copyright (c) 2026 UW Sauro Lab
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE.
+    """
+    x = np.asarray(times, dtype=float)
+    y = np.asarray(data, dtype=float)
+
+    if x.size != y.size:
+        raise ValueError("times and data must have the same length.")
+    if x.size < 3:
+        raise ValueError(
+            "At least 3 data points are required to generate a cubic spline."
+        )
+    if np.any(np.diff(x) <= 0):
+        sort_idx = np.argsort(x)
+        x = x[sort_idx]
+        y = y[sort_idx]
+        if np.any(np.diff(x) <= 0):
+            raise ValueError("time values must be strictly increasing.")
+
+    if monotone:
+        cs = PchipInterpolator(x, y)
+    else:
+        cs = CubicSpline(x, y, bc_type="natural")
+
+    n_segments = len(x) - 1
+    sep = ",\\ \n" if antimony_continuation else ",\n"
+    segments = []
+
+    for k in range(n_segments):
+        xk  = x[k]
+        xk1 = x[k + 1]
+        c3  = cs.c[0, k]   # cubic
+        c2  = cs.c[1, k]   # quadratic
+        c1  = cs.c[2, k]   # linear
+        c0  = cs.c[3, k]   # constant
+
+        def fmt(v: float) -> str:
+            return f"{v:+.6f}" if v < 0 else f"+{v:.6f}"
+
+        delay = f"({time_var}-{xk:.6f})"
+        expr = (
+            f"(({c3:.6f}*{delay}"
+            f"{fmt(c2)})*{delay}"
+            f"{fmt(c1)})*{delay}"
+            f"{fmt(c0)}"
+        )
+        condition = f"({time_var} >={xk:.6f}) && ({time_var} <= {xk1:.6f})"
+        segments.append(f"{expr}, {condition}")
+
+    body = sep.join(segments)
+    return f"{data_name} := piecewise ({body})"
+
+
+def generate_antimony_piecewise(
+    times: Union[List[float], np.ndarray, List[str]],
+    data: Union[List[float], np.ndarray, List[str]],
+    data_name: str = "data",
+    time_var: str = "time",
+    interpolation_type: str = "linear",
+    symbolic: bool = False,
+    time_tol: float = 1e-2,
+    **kwargs
+) -> str:
+    """
+    Generate an Antimony piecewise function with either linear or spline interpolation.
+    
+    Parameters
+    ----------
+    times : array-like
+        Vector of time points (must be sorted in ascending order)
+    data : array-like
+        Vector of data values corresponding to each time point
+    data_name : str
+        Name of the data variable in Antimony output (default: "data")
+    time_var : str
+        Name of the time variable in Antimony output (default: "time")
+    interpolation_type : str
+        "linear" or "spline" (default: "linear")
+    symbolic : bool
+        If True, treats time and data as strings for symbolic piecewise definition. (default: False)
+    time_tol : float
+        Tolerance for combining and averaging repeated time points (default: 1e-2)
+    **kwargs
+        Additional arguments passed to the specific interpolation function:
+        - For linear: default_before (float/str), default_after (float/str or None)
+        - For spline: antimony_continuation (bool), monotone (bool)
+        
+    Returns
+    -------
+    str
+        Antimony piecewise function definition
+    """
+    if not symbolic:
+        times = np.asarray(times, dtype=float)
+        data = np.asarray(data, dtype=float)
+        
+        # Sort by time to ensure proper ordering
+        sort_idx = np.argsort(times)
+        times = times[sort_idx]
+        data = data[sort_idx]
+        
+        # Average repeated times within tolerance
+        unique_times = []
+        unique_data = []
+        
+        i = 0
+        while i < len(times):
+            current_time_sum = times[i]
+            current_data_sum = data[i]
+            count = 1
+            
+            j = i + 1
+            while j < len(times) and (times[j] - times[i]) <= time_tol:
+                current_time_sum += times[j]
+                current_data_sum += data[j]
+                count += 1
+                j += 1
+                
+            unique_times.append(current_time_sum / count)
+            unique_data.append(current_data_sum / count)
+            
+            i = j
+            
+        times = np.array(unique_times)
+        data = np.array(unique_data)
+
+    if interpolation_type.lower() == "linear":
+        valid_kwargs = {k: v for k, v in kwargs.items() if k in ["default_before", "default_after"]}
+        if symbolic:
+            return _generate_linear_piecewise_symbolic(times, data, data_name, time_var, **valid_kwargs)
+        else:
+            return _generate_linear_piecewise(times, data, data_name, time_var, **valid_kwargs)
+    elif interpolation_type.lower() == "spline":
+        valid_kwargs = {k: v for k, v in kwargs.items() if k in ["antimony_continuation", "monotone"]}
+        return _generate_spline_piecewise(times, data, data_name, time_var, **valid_kwargs)
+    else:
+        raise ValueError(f"Unknown interpolation_type: {interpolation_type}. Must be 'linear' or 'spline'.")

framework/isotopomer_tools.py

@@ -0,0 +1,41 @@
+def ensure_isotopes_format(Isotopes):
+    """
+    Ensures that Isotopes is a list of strings and contains '' as an entry exactly once.
+    
+    Args:
+        Isotopes: Input that should be a list of strings (or convertible to one)
+    
+    Returns:
+        list: A list of strings with '' appearing exactly once
+    
+    Examples:
+        >>> ensure_isotopes_format(['L', '13C'])
+        ['', 'L', '13C']
+        >>> ensure_isotopes_format(['', '', 'L'])
+        ['', 'L']
+        >>> ensure_isotopes_format(['L'])
+        ['', 'L']
+    """
+    # Convert to list if not already
+    if not isinstance(Isotopes, list):
+        Isotopes = list(Isotopes) if hasattr(Isotopes, '__iter__') else [Isotopes]
+    
+    # Convert all entries to strings
+    Isotopes = [str(iso) for iso in Isotopes]
+    
+    # Remove all empty strings
+    Isotopes = [iso for iso in Isotopes if iso != '']
+    
+    # Remove duplicates while preserving order
+    seen = set()
+    Isotopes_unique = []
+    for iso in Isotopes:
+        if iso not in seen:
+            seen.add(iso)
+            Isotopes_unique.append(iso)
+    Isotopes = Isotopes_unique
+    
+    # Ensure '' appears exactly once at the beginning
+    Isotopes.insert(0, '')
+    
+    return Isotopes

framework/model_generation.py

@@ -0,0 +1,46 @@
+import os
+import sys
+
+from framework.antimony_utils import convert_to_antimony
+from framework.isotopomer_tools import ensure_isotopes_format
+
+def generate_model(build_reactions_func, Isotopes, calling_file_path, model_name):
+    """
+    Generates an Antimony model using the provided reaction building function.
+
+    Args:
+        build_reactions_func (callable): Function that takes Isotopes list and returns (all_reactions, rules).
+        Isotopes (list): List of isotopes to include.
+        calling_file_path (str): The __file__ path of the calling script, used to determine output filenames.
+        model_name (str): The name of the model to generate.
+    """
+    Isotopes = ensure_isotopes_format(Isotopes)
+    all_reactions, rules = build_reactions_func(Isotopes)
+
+    # Resolve to absolute path so output_dir does not depend on cwd (fixes VSCode "Run Python File" where cwd can be script dir)
+    script_dir = os.path.abspath(os.path.dirname(os.path.normpath(calling_file_path)))
+    # Project root: parent of "scripts", or two levels up when script is in scripts/Example/
+    if os.path.basename(script_dir) == "scripts":
+        output_dir = os.path.abspath(os.path.join(script_dir, ".."))
+    else:
+        output_dir = os.path.abspath(os.path.join(script_dir, "..", ".."))
+    generated_dir = os.path.join(output_dir, "generated", model_name)
+    os.makedirs(generated_dir, exist_ok=True)
+
+    # Output rules and reaction_dict using model_name only (one write each)
+    rules_path = os.path.join(generated_dir, f'{model_name}_rules.txt')
+    with open(rules_path, "w", encoding="utf-8") as f:
+        for rule in rules:
+            f.write(str(rule) + "\n")
+    print("Wrote to", rules_path)
+
+    model_path = os.path.join(generated_dir, f'{model_name}_reaction_dict.txt')
+    with open(model_path, "w", encoding="utf-8") as f:
+        for reaction in all_reactions:
+            f.write(str(reaction) + "\n")
+    print("Wrote to", model_path)
+
+    # Convert to Antimony format (use absolute paths so outputs go to project dir regardless of cwd)
+    model_path_abs = os.path.abspath(model_path)
+    rules_path_abs = os.path.abspath(rules_path)
+    convert_to_antimony(model_path_abs, model_name, rules_path_abs, output_dir=output_dir)

framework/models.py

@@ -0,0 +1,189 @@
+"""
+Structured models for PyAntiGen reactions and species.
+Replaces raw dict usage with validated dataclasses for clearer types and early validation.
+"""
+from dataclasses import dataclass
+from typing import List, Union, Optional
+
+# Valid rate types; RMA and BDF require two rate constants in Rate_eqtn_prototype
+VALID_RATE_TYPES = frozenset({
+    "RMA", "BDF", "MA", "UDF",
+    "custom_conc_per_time", "custom_amt_per_time", "custom"
+})
+
+RATE_TYPES_TWO_CONSTANTS = frozenset({"RMA", "BDF"})
+
+
+def normalize_species_list(value: Union[str, List[str], None]) -> List[str]:
+    """
+    Normalize reactants/products to a list of species name strings.
+    Accepts: None, list of strings, or string (e.g. '[A, B]' or '[A] + [B]').
+    """
+    if value is None:
+        return []
+    if isinstance(value, list):
+        return [str(s).strip() for s in value if s is not None and str(s).strip()]
+    s = str(value).strip()
+    if not s or s in ("0", "[0]"):
+        return []
+    return parse_species_list(s)
+
+
+def _ensure_string_list(value: Union[str, List[str]]) -> List[str]:
+    """Alias for normalize_species_list for internal use."""
+    return normalize_species_list(value)
+
+
+def parse_species_list(s: str) -> List[str]:
+    """
+    Parse a species list from string, supporting:
+      - '[A, B, C]' (comma-separated inside brackets)
+      - '[A] + [B]' or '[A]+[B]' (bracket-wrapped terms with +)
+    Returns list of stripped species names. Uses regex to extract bracketed or comma-separated tokens.
+    """
+    import re
+    s = s.strip()
+    if not s:
+        return []
+    # Already a single token (no brackets, no comma)
+    if not re.search(r'[\[\],+]', s):
+        return [s] if s and s != "0" else []
+    inner = s.strip()
+    # Only remove outer brackets for "[A, B]" style (single list), not "[A] + [B]"
+    if inner.startswith('[') and inner.endswith(']') and '+' not in inner[1:-1]:
+        inner = inner[1:-1].strip()
+    if not inner:
+        return []
+    # Split by comma only if we're in bracket list form (no + in the middle)
+    if '+' not in inner:
+        return [x.strip() for x in re.split(r'\s*,\s*', inner) if x.strip()]
+    # "[A] + [B]" or "A + B" form: split by + and clean each part
+    parts = re.split(r'\s*\+\s*', inner)
+    result = []
+    for p in parts:
+        p = p.strip()
+        if p.startswith('[') and p.endswith(']'):
+            p = p[1:-1].strip()
+        if p and p != "0":
+            result.append(p)
+    return result
+
+
+def parse_rate_equation_list(rate_proto: Union[str, List[str]], rate_type: str) -> List[str]:
+    """
+    Parse Rate_eqtn_prototype into a list of one or two rate expression strings.
+    For RMA/BDF we expect two constants; for others one.
+    """
+    if rate_proto is None:
+        return []
+    if isinstance(rate_proto, list):
+        return [str(x).strip() for x in rate_proto if str(x).strip()]
+    s = str(rate_proto).strip()
+    if not s:
+        return []
+    if s.startswith('[') and s.endswith(']'):
+        inner = s[1:-1].strip()
+        return [x.strip() for x in inner.split(',') if x.strip()]
+    return [s]
+
+
+@dataclass(frozen=True)
+class Species:
+    """A species with optional explicit compartment (otherwise inferred from name suffix)."""
+    name: str
+    compartment: Optional[str] = None
+
+    def resolve_compartment(self) -> str:
+        """Compartment to use: explicit if set, else last segment after underscore."""
+        if self.compartment is not None:
+            return self.compartment
+        if '_' in self.name:
+            return self.name.split('_')[-1]
+        return self.name
+
+
+@dataclass
+class Reaction:
+    """
+    A single reaction with validated fields.
+    Reactants and Products are stored as lists of species names.
+    Rate_eqtn_prototype is one string (MA, UDF, custom) or two (RMA, BDF).
+    """
+    Reaction_name: str
+    Reactants: List[str]
+    Products: List[str]
+    Rate_type: str
+    Rate_eqtn_prototype: Union[str, List[str]]
+    # Optional: explicit compartment(s) so framework doesn't infer from name suffix
+    compartment: Optional[str] = None
+    compartment_reverse: Optional[str] = None  # for product side when different
+
+    def __post_init__(self):
+        r = self.Reaction_name.replace(" ", "") if self.Reaction_name else "NA"
+        object.__setattr__(self, 'Reaction_name', r)
+        if self.Rate_type and self.Rate_type not in VALID_RATE_TYPES:
+            raise ValueError(
+                f"Invalid Rate_type '{self.Rate_type}'. "
+                f"Valid types: {', '.join(sorted(VALID_RATE_TYPES))}"
+            )
+        rate_list = parse_rate_equation_list(self.Rate_eqtn_prototype, self.Rate_type)
+        if self.Rate_type == "RMA" and len(rate_list) < 2:
+            raise ValueError(
+                f"RMA reaction requires two rate constants in Rate_eqtn_prototype, got: {self.Rate_eqtn_prototype!r}"
+            )
+        if self.Rate_type == "BDF" and len(rate_list) < 1:
+            raise ValueError(
+                f"BDF reaction requires at least one rate constant in Rate_eqtn_prototype, got: {self.Rate_eqtn_prototype!r}"
+            )
+
+    def to_dict(self) -> dict:
+        """Export as dict for serialization and RxnDict_to_antimony compatibility."""
+        # Serialize reactants/products as "[A, B]" for file format compatibility
+        def to_bracket(lst):
+            if not lst:
+                return "[0]"
+            return "[" + ", ".join(lst) + "]"
+        rate = self.Rate_eqtn_prototype
+        if isinstance(rate, list):
+            rate = "[" + ", ".join(rate) + "]"
+        d = {
+            "Reaction_name": self.Reaction_name,
+            "Reactants": to_bracket(self.Reactants),
+            "Products": to_bracket(self.Products),
+            "Rate_type": self.Rate_type,
+            "Rate_eqtn_prototype": rate,
+        }
+        if self.compartment is not None:
+            d["compartment"] = self.compartment
+        if self.compartment_reverse is not None:
+            d["compartment_reverse"] = self.compartment_reverse
+        return d
+
+
+def reaction_from_args(
+    name: str,
+    reactants: Union[str, List[str]],
+    products: Union[str, List[str]],
+    rate_type: str,
+    rate_eqtn: Union[str, List[str]],
+    compartment: Optional[str] = None,
+    compartment_reverse: Optional[str] = None,
+) -> Reaction:
+    """Build and validate a Reaction from add_reaction-style arguments."""
+    if not name or not name.strip():
+        name = "NA"
+    if rate_type is None or rate_type == "":
+        raise ValueError("Rate_type is required")
+    if rate_eqtn is None or (isinstance(rate_eqtn, str) and rate_eqtn.strip() == ""):
+        raise ValueError("Rate_eqtn_prototype is required")
+    reactants_list = _ensure_string_list(reactants)
+    products_list = _ensure_string_list(products)
+    return Reaction(
+        Reaction_name=name.strip().replace(" ", ""),
+        Reactants=reactants_list,
+        Products=products_list,
+        Rate_type=rate_type.strip(),
+        Rate_eqtn_prototype=rate_eqtn,
+        compartment=compartment,
+        compartment_reverse=compartment_reverse,
+    )

framework/module_base.py

@@ -0,0 +1,42 @@
+class PyAntiGenModule:
+    """
+    Base class for declarative PyAntiGen modules.
+    Modules should inherit from this and implement the build() method.
+    When instantiated, the module will automatically build and add its reactions 
+    to the passed PyAntiGen model instance.
+    """
+    def __init__(self, model, **kwargs):
+        self.model = model
+        self.config = kwargs
+        
+        # Build reactions automatically on init
+        self.build()
+
+    def build(self):
+        """Override this in subclasses to define reactions."""
+        raise NotImplementedError("Modules must implement a build() method.")
+
+    def add_reaction(
+        self,
+        name,
+        reactants,
+        products,
+        rate_type,
+        rate_eqtn,
+        compartment=None,
+        compartment_reverse=None,
+    ):
+        """Helper to add reactions directly into the parent model."""
+        self.model.add_reaction(
+            name,
+            reactants,
+            products,
+            rate_type,
+            rate_eqtn,
+            compartment=compartment,
+            compartment_reverse=compartment_reverse,
+        )
+
+    def add_rule(self, rule):
+        """Helper to add rules directly into the parent model."""
+        self.model.add_rule(rule)