X2Power Simulator
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.
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.
- Website: asvaconsulting.com
- Contact: contacto@asvaconsulting.com
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.