Metadata-Version: 2.5
Name: pepkio-osmo-recipe-solver
Version: 0.1.0
Summary: Python client for Pepkio osmo-recipe-solver tool
Author-email: Pepkio Team <tools@pepkio.com>
Requires-Python: >=3.11
Requires-Dist: click>=8.4.2
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic>=2.13.4
Description-Content-Type: text/markdown

# Osmo Recipe Solver

A Python package and command-line interface for calculating multi-solute solution osmolarity, predicting osmotic pressure, and reconciling target buffer recipes for laboratory research.

# What It Does

`pepkio-osmo-recipe-solver` provides computational tools to determine theoretical osmolarity ($\text{mOsm/L}$), compute total ionic strength, assess solution tonicity, and reconcile solute concentrations in multi-component aqueous solutions.

Researchers can compute total osmolarity from molar solute inputs, evaluate tonicity relative to standard biological baselines (e.g., ~290 mOsm/L for mammalian physiological fluids), and automatically solve for the solute mass or concentration required to achieve a specific target osmolarity.

# Features

- **Multi-Solute Osmolarity Calculation**: Computes theoretical solution osmolarity ($\text{mOsm/L}$) across ionic salts, organic buffers, and non-electrolyte mixtures.
- **Stoichiometric Dissociation Accounting**: Applies van 't Hoff dissociation factors ($\nu$) for electrolytes, polyvalent salts, and non-dissociating compounds.
- **Tonicity Classification**: Evaluates effective tonicity and categorizes formulations as isotonic, hypotonic, or hypertonic against physiological reference standards.
- **Automated Recipe Reconciliation**: Solves for the required adjusting solute concentration (e.g., $\text{NaCl}$, sucrose, or mannitol) to meet a specified target osmolarity.
- **Ionic Strength Computation**: Calculates total ionic strength ($I$) to assist in buffer formulation for protein chemistry and enzyme kinetics.
- **Python API & CLI**: Provides both a programmatic Python client and a command-line interface for integration into automated laboratory pipelines.

# Installation

Install the package from PyPI using `pip`:

```bash
pip install pepkio-osmo-recipe-solver
```

# Quick Example

```python
from pepkio_osmo_recipe_solver import PepkioClient, OsmoSolverInput, SoluteInputRow

# Initialize client (reads PEPKIO_API_KEY environment variable if set)
client = PepkioClient(api_key="your_api_key")

# Define a standard 1X Phosphate-Buffered Saline (PBS) solution
pbs_input = OsmoSolverInput(
    tab="calculator",
    solutes=[
        SoluteInputRow(solute_id="nacl", concentration=137, unit="mM"),
        SoluteInputRow(solute_id="kcl", concentration=2.7, unit="mM"),
        SoluteInputRow(solute_id="na2hpo4", concentration=10, unit="mM"),
        SoluteInputRow(solute_id="kh2po4", concentration=1.8, unit="mM"),
    ]
)

# Compute osmolarity and tonicity
result = client.run(pbs_input)
calc = result.result["calculator"]

print(f"Total Osmolarity: {calc['total_osmolarity_mOsm_L']} mOsm/L")
print(f"Tonicity Classification: {calc['tonicity_label']}")
```

# Typical Use Cases

- **Electrophysiology & Patch-Clamp**: Formulating internal pipette solutions and external bath formulations (aCSF) to match physiological osmolarity targets (290–310 mOsm/kg).
- **Cell Culture & Organoid Media**: Adjusting basal media and serum-free buffers to maintain cell membrane stability and prevent osmotic shock.
- **Cryopreservation Formulations**: Computing multi-solute cryoprotectant mixtures containing DMSO, glycerol, or trehalose to minimize intracellular ice formation.
- **Protein Chemistry & Chromatography**: Determining salt concentrations and ionic strength for ion-exchange and hydrophobic interaction chromatography buffers.
- **Plant Protoplast Isolation**: Preparing hypertonic stabilization buffers with mannitol or sorbitol to maintain protoplast integrity.

# Scientific Background

Theoretical osmolarity for a solution containing $N$ distinct solutes is calculated as:

$$\text{Osmolarity (mOsm/L)} = \sum_{i=1}^{N} \nu_i \cdot C_i \times 1000$$

where $\nu_i$ is the stoichiometric dissociation factor (van 't Hoff number) and $C_i$ is the solute molar concentration ($\text{mol/L}$).

Key physical concepts include:
- **Osmotic Pressure ($\Pi$)**: Calculated via the van 't Hoff relation $\Pi = \text{Osmolarity} \cdot R \cdot T$, where $R$ is the ideal gas constant and $T$ is absolute temperature.
- **Ionic Strength ($I$)**: Defined as $I = \frac{1}{2} \sum c_i z_i^2$, reflecting the total electrostatic field produced by dissolved ions.
- **Osmolarity vs. Osmolality**: Osmolarity measures solute osmoles per liter of final solution ($\text{mOsm/L}$), whereas osmolality measures osmoles per kilogram of solvent ($\text{mOsm/kg H}_2\text{O}$). In dilute room-temperature aqueous solutions, the numerical values are nearly identical.

# Web Application

For researchers who prefer a graphical interface, an interactive web version is available.

Web Application: https://www.pepkio.com/tools/osmo-recipe-solver

Web-only features include interactive visual buffer design, live tonicity scale visualization, shareable recipe permalinks, and printable laboratory bench protocols and worksheets.

# Documentation and Resources

GitHub Repository: https://github.com/pepkio/pepkio-osmo-recipe-solver

Web Application: https://www.pepkio.com/tools/osmo-recipe-solver

Source code, issue tracking, and developer updates are maintained on GitHub.

# About Pepkio

Pepkio (https://www.pepkio.com/) develops software tools and bioinformatics solutions for life science researchers, including laboratory calculators and analysis services (https://www.pepkio.com/cro).

# Keywords

* pepkio-osmo-recipe-solver, osmo-recipe-solver, osmolarity calculator, osmolality calculator, buffer recipe solver, tonicity calculator, ionic strength calculator, osmotic pressure, van t Hoff factor, dissociation constant, cell culture buffer, electrophysiology aCSF, patch clamp pipette solution, cryopreservation buffer, PBS osmolarity, NaCl dissociation, protoplast isolation buffer, mannitol osmolarity, solution preparation, stock solution dilution, molarity to osmolarity, isotonic solution, hypertonic buffer, hypotonic solution, lab buffer calculator
* how to calculate osmolarity of multi solute solution, how to calculate osmolality from molar concentration, how to adjust buffer tonicity for cell culture, electrophysiology internal solution osmolarity recipe, how to prepare 1X PBS buffer osmolarity, difference between osmolarity and osmolality in biology, how does van t Hoff factor affect osmolarity, calculating ionic strength of buffer solution, osmotic pressure formula van t Hoff equation, how to make isotonic solution for mammalian cells, cryoprotectant osmolarity calculation trehalose sucrose, protoplast osmotic stabilization mannitol sorbitol, how to solve buffer recipe target osmolarity, Python library for buffer osmolarity calculations, CLI tool for lab solution preparation
