{"id":34591314,"url":"https://github.com/daggbt/composite-diffuse-layer-calc","last_synced_at":"2026-06-05T07:31:21.414Z","repository":{"id":175049678,"uuid":"487187781","full_name":"daggbt/composite-diffuse-layer-calc","owner":"daggbt","description":"CDL calculation","archived":false,"fork":false,"pushed_at":"2025-12-18T17:06:44.000Z","size":712,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-21T20:41:48.431Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/daggbt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-04-30T05:11:47.000Z","updated_at":"2025-12-18T17:06:48.000Z","dependencies_parsed_at":null,"dependency_job_id":"5dc8357b-f17b-4368-8c3c-27fd03cc7bdd","html_url":"https://github.com/daggbt/composite-diffuse-layer-calc","commit_stats":null,"previous_names":["daggbt/cdl_calculations_repo","daggbt/composite-diffuse-layer-calc"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/daggbt/composite-diffuse-layer-calc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daggbt%2Fcomposite-diffuse-layer-calc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daggbt%2Fcomposite-diffuse-layer-calc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daggbt%2Fcomposite-diffuse-layer-calc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daggbt%2Fcomposite-diffuse-layer-calc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/daggbt","download_url":"https://codeload.github.com/daggbt/composite-diffuse-layer-calc/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daggbt%2Fcomposite-diffuse-layer-calc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33934426,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-05T02:00:06.157Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-24T10:51:33.758Z","updated_at":"2026-06-05T07:31:21.407Z","avatar_url":"https://github.com/daggbt.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Composite Diffuse Layer (CDL) Calculator\n\n**CDL (Composite Diffuse Layer)** is a Python package for modeling the electric double layer (EDL) in supercapacitors. It implements a modified Poisson-Boltzmann theory that accounts for steric repulsion (finite ion size) at high potentials, transitioning from Gouy-Chapman behavior at low potentials to a condensed \"steric layer\" at high potentials.\n\nThis repo allows for the calculation of differential capacitance, spatial profiles (potential, electric field, concentration), and thermodynamic properties (free energy components) for both single-electrode (half-cell) and double-electrode (full-cell) configurations.\n\nThe model is based on the research article:\n\u003e **\"The impact of steric repulsion on the total free energy of electric double layer capacitors\"**  \n\u003e Dagmawi B. Tadesse and Drew F. Parsons  \n\u003e *Colloids and Surfaces A: Physicochemical and Engineering Aspects*, 648, 129134 (2022).  \n\u003e [DOI: 10.1016/j.colsurfa.2022.129134](https://doi.org/10.1016/j.colsurfa.2022.129134)\n\n## Features\n\n*   **Hybrid Model**: Seamlessly transitions between Gouy-Chapman (diffuse) and Steric (condensed) regimes.\n*   **Asymmetric Electrolytes**: Handles ions with different sizes and valencies (e.g., Li+ vs PF6-).\n*   **Double Electrode Simulation**: Correctly calculates potential splitting in full cells due to charge conservation and asymmetry.\n*   **Thermodynamics**: Computes Entropic, Electrostatic, and Steric free energy components.\n*   **Spatial Profiling**: Visualizes potential $\\Phi(x)$, electric field $E(x)$, ion concentrations $c(x)$, and charge density $\\rho(x)$.\n*   **Flexible API**: Use via Command Line Interface (CLI) or as a Python library.\n\n## Installation\n\n### Prerequisites\n*   Python 3.10+\n*   `uv` (recommended) or `pip`\n\n### Setup\n\n1.  **Clone the repository:**\n    ```bash\n    git clone https://github.com/daggbt/composite-diffuse-layer-calc.git\n    cd composite-diffuse-layer-calc\n    ```\n\n2.  **Install dependencies:**\n    ```bash\n    # Using uv\n    uv sync\n\n    # Or using pip\n    pip install numpy scipy matplotlib\n    ```\n\n## Command Line Interface (CLI)\n\nThe `main.py` script provides a robust CLI for running simulations and generating plots.\n\n### 1. Voltage Dependence (Capacitance \u0026 Free Energy)\nCalculate properties over a voltage sweep.\n\n```bash\n# Single Electrode (Half-Cell)\nuv run main.py --single-electrode --plot-voltage-dep --output capacitance_curve.png\n\n# Double Electrode (Full-Cell)\nuv run main.py --double-electrode --plot-voltage-dep --output full_cell_capacitance.png\n```\n\n**Options:**\n*   `--cation`, `--anion`: Select ions (e.g., `Li`, `K`, `PF_6`, `Cl`, `TFSI`).\n*   `--solvent`: Select solvent (e.g., `Propylene_Carbonate`, `Water`).\n*   `--conc`: Bulk concentration in M (default: 1.0).\n*   `--v-min`, `--v-max`: Voltage sweep range in mV.\n\n\u003cimg src=\"output/voltage_dependence.png\" alt=\"Voltage Dependence\" width=\"85%\"\u003e\n*Figure 2: Voltage dependence of Differential Capacitance, Steric Layer Thickness, and Free Energy components.*\n\n### 2. Spatial Profiles\nVisualize the structure of the double layer at a specific potential.\n\n```bash\n# Plot profiles at 1000 mV (1 V)\nuv run main.py --double-electrode --plot-profiles --potential 1000 --output profiles.png\n```\n\n\u003cimg src=\"output/spatial_profiles.png\" alt=\"Spatial Profiles\" width=\"85%\"\u003e\n*Figure 1: Spatial profiles of Potential, Electric Field, Concentration, and Charge Density in a double electrode setup.*\n\n## Python API\n\nFor advanced usage, integration, or batch processing, use the `cdl` package directly. The `cdl.calculations` module provides high-level access to physical quantities.\n\n### Initialization\n\n```python\nfrom cdl.models import SimulationParameters\nfrom cdl.database import IONS, SOLVENTS\n\n# Define system parameters\nparams = SimulationParameters(\n    electrolyte_ions=(IONS['Li'], IONS['PF_6']),\n    solvent=SOLVENTS['Propylene_Carbonate'],\n    bulk_concentration=1.0,          # 1 M\n    single_electrode=False,          # Double electrode (Full cell)\n    separation_distance=20.0         # 20 * Debye Length\n)\n```\n\n### Calculating Spatial Properties\nGet values at a specific distance $x$ (meters) from the left electrode.\n\n```python\nfrom cdl.calculations import (\n    get_potential_at_x, \n    get_electric_field_at_x, \n    get_concentration_at_x\n)\n\nV_cell = 1000.0 # 1 V potential difference\nx_pos = 1e-9    # 1 nm\n\n# Electric Potential (V)\nphi = get_potential_at_x(params, x_pos, V_cell)\n\n# Electric Field (V/m)\nE_field = get_electric_field_at_x(params, x_pos, V_cell)\n\n# Ion Concentrations (M)\nconcs = get_concentration_at_x(params, x_pos, V_cell)\nprint(f\"Li+: {concs['cation']} M, PF6-: {concs['anion']} M\")\n```\n\n### Calculating Macroscopic Properties\nGet properties as a function of applied voltage $V$.\n\n```python\nfrom cdl.calculations import (\n    get_total_capacitance, \n    get_free_energy, \n    get_potential_split\n)\n\n# Total Differential Capacitance (F/m^2)\nC_diff = get_total_capacitance(params, V_cell)\n\n# Free Energy Components (J/m^2)\nenergies = get_free_energy(params, V_cell)\nprint(f\"Total Energy: {energies['total']} J/m^2\")\nprint(f\"Steric Contribution: {energies['steric']} J/m^2\")\n\n# Potential Drop across Electrodes (mV)\nphi_left, phi_right = get_potential_split(params, V_cell)\nprint(f\"Left Electrode: {phi_left} mV, Right Electrode: {phi_right} mV\")\n```\n\n## Configuration\n\nYou can modify default simulation parameters in `config.py` or override them via CLI arguments.\n\n```python\n# config.py\nCATION = \"Li\"\nANION = \"PF_6\"\nSOLVENT = \"Propylene_Carbonate\"\nBULK_CONCENTRATION = 1.0\nSINGLE_ELECTRODE = False\n```\n\n## Citation\n\nIf you use this repo in your research, please cite the following article:\n\n```bibtex\n@article{TADESSE2022129134,\ntitle = {The impact of steric repulsion on the total free energy of electric double layer capacitors},\njournal = {Colloids and Surfaces A: Physicochemical and Engineering Aspects},\nvolume = {648},\npages = {129134},\nyear = {2022},\nissn = {0927-7757},\ndoi = {10.1016/j.colsurfa.2022.129134},\nurl = {https://www.sciencedirect.com/science/article/pii/S0927775722008895},\nauthor = {Dagmawi B. Tadesse and Drew F. Parsons},\nkeywords = {Supercapacitor, Electric double layer capacitor, Modified Poisson-Boltzmann, Steric interaction, Steric layer, Composite diffuse layer, Total Free Energy},\nabstract = {We present an analysis of the total free energy of a supercapacitor modelled with a composite diffuse layer (CDL) formed by a steric repulsive potential. The steric potential is modelled with a simple approximation to the Bikerman steric potential, enabling derivation of an analytical expression for the total free energy of the supercapacitor in terms of the size and valency of the electrolyte counterions and electrode potentials. The analytical expression for the total free energy of the supercapacitor matches the exact numerical Bikerman calculation at high potential with relative error close to 1%. This provides an upper bound over the more accurate Carnahan-Starling model. A maximum upper bound for the energy is also provided in the limit where bulk concentrations approach the ion concentration cap. We analyze the relative contribution of the steric interaction to the total free energy. At large voltages, the steric free energy is comparable in magnitude to that of the electrostatic free energy, and introduces ion-size effects in the energy of the supercapacitor. Consequently at high potentials the total free energy exceeds (doubles) the classical energy 1/2CV^2, indicating that this formula does not correctly describe the available stored energy from the experimentally measured capacitance.}\n}\n```\n\n## License\n\n[MIT License](LICENSE)\n\n```bash\nuv run main.py --cation Li --anion PF_6 --solvent Propylene_Carbonate --output result.png\n```\n\n### Command Line Arguments\n\n| Argument | Description | Default |\n| :--- | :--- | :--- |\n| `--cation` | Name of the cation (e.g., `Li`, `Na`, `K`) | `hydLi5Ion` |\n| `--anion` | Name of the anion (e.g., `PF_6`, `Cl`) | `PF_6` |\n| `--solvent` | Name of the solvent | `Propylene_Carbonate` |\n| `--conc` | Bulk concentration in Molar (mol/L) | `1.0` |\n| `--v-min` | Minimum voltage in mV | `-1000` |\n| `--v-max` | Maximum voltage in mV | `1000` |\n| `--steps` | Number of voltage steps | `100` |\n| `--single-electrode` | Simulate a single electrode instead of a full cell | `False` |\n| `--output` | Path to save the resulting plot (e.g., `plot.png`) | None (shows plot) |\n\n### Available Ions and Solvents\n\nCheck `src/cdl/database.py` for the full list of available ions and solvents. Common options include:\n*   **Cations**: `Li`, `Na`, `K`, `hydLi5Ion`, `EM`\n*   **Anions**: `PF_6`, `BF_4`, `ClO_4`, `TFSI`, `Cl`\n*   **Solvents**: `Propylene_Carbonate`, `Water`\n\n## Project Structure\n\nThe codebase has been refactored for modularity and maintainability:\n\n```\ncomposite-diffuse-layer-calc/\n├── src/\n│   └── cdl/\n│       ├── models.py       # Data structures (Ion, Solvent, SimulationParameters)\n│       ├── physics.py      # Core physics calculations (Debye length, etc.)\n│       ├── solvers.py      # Numerical solvers for potential and capacitance\n│       └── database.py     # Registry of ion and solvent properties\n├── tests/                  # Unit tests\n├── main.py                 # CLI entry point\n└── pyproject.toml          # Project configuration\n```\n\n## Development\n\nTo run the unit tests:\n\n```bash\nuv run pytest\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaggbt%2Fcomposite-diffuse-layer-calc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdaggbt%2Fcomposite-diffuse-layer-calc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaggbt%2Fcomposite-diffuse-layer-calc/lists"}