Skip to main content

X2Power Simulator

ASVA Consulting

Created by ASVA Consulting
asvaconsulting.com
contacto@asvaconsulting.com

Created and maintained by ASVA Consulting, X2Power is a Python simulator for converting solid feedstocks, biogas and organic wastewater into electricity. It calculates gross generation, net electricity, process heat, auxiliary consumption and capacity constraints using explicit energy balances.

The simulation core has no runtime dependencies and requires Python 3.11 or newer. Install the optional plots extra for Matplotlib figures. Models are reduced-order, interval-based calculations. Route scenarios and plant presets are synthetic examples. Source-backed analyses distinguish published data from assumptions and simulated equipment performance.

Documentation · Example gallery · API reference

AI-assisted development and literature basis

Most of the code, documentation, examples, tests and repository scaffolding are AI-generated under developer direction, based on real, specifically identified scientific and technical literature selected by the repository developers.

Developers choose the references used to define physical assumptions, methods and parameter conventions. AI assists with implementation, documentation, testing and iteration around that evidence base. Developers and contributors remain responsible for source selection, review, testing and scientific validation.

AI-generated code and explanations may contain errors or imperfect interpretations of the selected sources. Automated tests establish numerical consistency; they do not establish empirical accuracy. Validation is still developing. The original route scenarios and continuous-plant presets are synthetic illustrative inputs. Source-backed analyses separately identify published measurements, assumptions and simulated results; cited laboratory data do not validate plant performance.

Trace assumptions through the model references, biogas plant references and plastic example boundaries. See verification and calibration for the evidence available and the checks needed before interpreting results as equipment predictions.

Quick start

Install the published package from PyPI:

python -m pip install x2power-simulator
x2power --version

For optional plotting, install "x2power-simulator[plots]". The wheel provides the x2power Python package and CLI. The scenario files, runnable analyses and gallery sources are in the repository and source distribution. To run those examples:

git clone https://github.com/julianascencio/x2power-simulator.git
cd x2power-simulator
python -m venv .venv
source .venv/bin/activate
python -m pip install -e .
x2power run use_cases/scenarios/biogas_engine.json

On Windows, activate with .venv\Scripts\Activate.ps1 in PowerShell. The equivalent module command is python -m x2power.

Save a full result or compare scenarios:

x2power run use_cases/scenarios/organic_wastewater.json -o results/wastewater.json
x2power compare use_cases/scenarios/biomass_gasification.json use_cases/scenarios/biomass_combustion.json --csv results/comparison.csv

Comparisons preserve each scenario's feed amount and interval length. Normalize these inputs before interpreting differences as conversion performance.

Conversion methods

Route Calculation basis Example
Combustion Dry-feed LHV, boiler energy recovery and power-block efficiency Biomass
Gasification Dry-feed LHV and selected fuel-gas energy recovery Biomass
Pyrolysis Dry-feed LHV and combined energy recovery in selected fuel products Plastic
Anaerobic digestion Volatile solids destroyed and methane yield Food waste, sludge
Organic wastewater COD removed and methane yield Organic wastewater
Biogas generation Dry normal gas volume and methane fraction Biogas engine

Every route uses the same generation model, with optional gross power rating, availability, heat recovery, electric heating and auxiliary loads. Negative net electricity is retained and indicates a need for external electrical supply.

Python API

from x2power import AuxiliaryLoads, Generator, SolidFeedstock
from x2power.methods import ThermalProcess, simulate_thermal

result = simulate_thermal(
    SolidFeedstock(mass_kg=100, moisture_fraction=0.2, dry_lhv_mj_per_kg=18),
    ThermalProcess(
        route="gasification",
        fuel_energy_recovery=0.7,
        evaporation_heat_kwh_per_kg_water=0.7,
        process_heat_kwh_per_kg_dry=0.2,
    ),
    Generator(electrical_efficiency=0.3, heat_recovery_efficiency=0.4),
    duration_h=1,
    auxiliaries=AuxiliaryLoads(process_heat_usable_fraction=0),
)

print(result.power.gross_electricity_kwh)  # 84.0
print(result.power.net_electricity_kwh)  # 54.0

This example supplies process heat electrically. Set the usable recovered-heat fraction only when the available heat matches the required temperature and duty.

Repository layout

Folder Purpose
src/x2power/methods/ Conversion models, shared generation model and operating profiles
src/x2power/utilities/ Validation, unit conversions, JSON/CSV, sweeps and Monte Carlo experiments
use_cases/ Runnable examples, seven route scenarios and three continuous plant configurations
analysis/ Reproducible source-backed cases, cost-benefit screening and pinned results
tests/ Hand-calculated cases, conservation checks, limiting cases and CLI integration
docs/ Equations, configuration reference, assumptions and validation guidance

Run the included experiments after installation:

python use_cases/compare_routes.py
python use_cases/moisture_sweep.py
python use_cases/operating_profile.py
python use_cases/uncertainty.py

Outputs are written to results/ in the current working directory. See the use-case guide for what each experiment measures.

Plot simulation results

python -m pip install -e '.[plots]'
x2power plot use_cases/scenarios/biomass_gasification.json -o results/energy_balance.png
python use_cases/visual_report.py

The worked example writes electricity/heat, moisture sensitivity, operating profile and uncertainty figures as PNG and SVG. Its JSON output retains the scenario inputs, experiment settings, seed, sample draws and numerical results. CSV tables expose the sensitivity sweep and interval powers. See the plotting guide.

Synthetic moisture sensitivity example

Plastic to electricity

python use_cases/plastic_to_power.py --plot

The synthetic example follows 2 tonnes of wet feed over 24 hours through pyrolysis fuel recovery and electricity generation, including process heat and auxiliaries. It exports three figures, two sensitivity tables and a full JSON result. Install the plots extra for figures, or omit --plot for a dependency-free run. See the guide and step-by-step gallery.

Continuous biogas plants

Simulate mixed organic feeds, a continuously stirred digester, gas storage and CHP with hourly operating schedules. Includes generic agroindustrial, dairy-manure and swine-slurry configurations, all with synthetic inputs.

python use_cases/biogas_plant.py --plant agroindustrial_chp --days 30 --plot

Install the plots extra for figures. The example records substrate/gas inventories, net electricity, grid imports/exports, flaring and heat demand in JSON/CSV. See the plant model and assumptions and step-by-step gallery.

Source-backed banana-residue analysis

python -m analysis.tenerife_banana.run --plot

The Tenerife screening case combines published island context and Gran Canaria laboratory pseudostem measurements with explicit engineering and cost assumptions. It models 365 daily energy balances, grid imports/exports, NPV, benefit/cost ratio, payback, gross LCOE and break-even sensitivities. The baseline is financially negative under its stated assumptions; it is not an operating-plant reconstruction.

Reusable financial functions live in src/x2power/methods/cost_benefit.py; the offline workflow and pinned numeric results are under analysis/tenerife_banana/. See the evidence and reproduction guide and results gallery.

Route model boundaries

  • Input masses and volumes are totals over the simulation interval, not rates.
  • Heating values and conversion efficiencies use the lower heating value (LHV) basis.
  • Gas volumes use a dry normal state of 0 °C and 101325 Pa.
  • Fuel arrives uniformly; unavailable hours and capacity limits leave unused fuel. There is no implicit fuel storage or rescheduling.
  • Usable recovered heat offsets process demand. Remaining demand is supplied by an electric resistance heater and deducted from net electricity.
  • Energy closure is checked at the generator boundary. No detailed reaction, product-speciation, emissions, gas-cleaning or reactor-kinetics model is included.
  • The original route profiles combine independent steady intervals. The continuous biogas plant module separately tracks substrate and gas inventories. Monte Carlo quantiles describe the chosen input distributions, not calibrated confidence intervals.

Read equations and boundaries, the scenario reference and validation guidance before adapting a scenario.

Development

python -m pip install -e '.[dev,plots]'
ruff check .
ruff format --check .
ty check src use_cases analysis
pytest --cov=x2power --cov-report=term-missing
python -m build

CI runs the tests on Python 3.11–3.14 and checks formatting, static types and package builds. The coverage threshold is 85%, including branches. See CONTRIBUTING.md for model contribution requirements.

Build the Sphinx documentation and execute the gallery locally:

python -m pip install -e '.[docs]'
sphinx-build -W --keep-going -b html docs docs/_build/html

GitHub Actions validates documentation on pull requests and publishes successful builds from main to GitHub Pages. See documentation development.

Creator and contact

X2Power is owned, created and maintained by ASVA Consulting, with contributions from the repository developers and contributors.

Metadata

Release files for x2power-simulator 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for x2power-simulator 0.1.0
File Size Uploaded Provenance Actions
x2power_simulator-0.1.0.tar.gz 110.3 kB Without provenance Details for x2power_simulator-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for x2power-simulator 0.1.0
File Interpreter ABI Platform Actions
x2power_simulator-0.1.0-py3-none-any.whl Python 3 none any Details for x2power_simulator-0.1.0-py3-none-any.whl

Total release size: 145.9 kB

Release files / x2power_simulator-0.1.0.tar.gz

Download URL x2power_simulator-0.1.0.tar.gz
Size 110.3 kB
Tags Source
SHA-256 checksum
How to use checksums
401f4765231d8c01928738dbc5a8fe35c5e2ae6fcbdec524cdb6ced335ca9aa1
BLAKE2b-256 checksum
How to use checksums
c584931d63b0199bdac9858049370c91c270c9bd7d946246631531af84163811
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / x2power_simulator-0.1.0-py3-none-any.whl

Download URL x2power_simulator-0.1.0-py3-none-any.whl
Size 35.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6c8be81875d9d7b29e91b2b1d5b01c1806c267520f51722e6bd5406ac4583fb7
BLAKE2b-256 checksum
How to use checksums
05cbf6b3f3c97f3f70997f8d7ae5f5e878d6f849027f5c34d497ff7c48c32a3d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for x2power-simulator 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page