Metadata-Version: 2.4
Name: el1xr_opt
Version: 1.0.8
Summary: An open-source optimization model for the design and operation of hybrid renewable energy systems with automatic solver setup
Author-email: EL1XR-dev Team <erik.alvarez@ri.se>
Requires-Python: >=3.11
Description-Content-Type: text/x-rst
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
License-File: LICENSE
Requires-Dist: pyomo>=6.8.0
Requires-Dist: matplotlib>=3.3.4
Requires-Dist: numpy>=1.20.1
Requires-Dist: pandas>=1.2.3
Requires-Dist: plotly>=5.7.0
Requires-Dist: colour>=0.1.5
Requires-Dist: altair>=5.0.0
Requires-Dist: psutil>=5.8.0
Requires-Dist: jsonschema>=4.16.0
Requires-Dist: streamlit>=1.38.0
Requires-Dist: networkx>=3.3
Requires-Dist: ausankey>=1.5.0
Requires-Dist: amplpy>=0.15.0
Project-URL: Homepage, https://el1xr_opt.readthedocs.io/en/latest/index.html
Project-URL: Issues, https://github.com/EL1XR-dev/el1xr_opt/issues
Project-URL: Repository, https://github.com/EL1XR-dev/el1xr_opt

el1xr_opt
=========
.. image:: https://raw.githubusercontent.com/EL1XR-dev/el1xr_opt/refs/heads/main/docs/img/el1xr_opt_logo_v6.png
   :width: 120
   :align: right
   :alt: EL1XR logo

|

.. image:: https://badge.fury.io/py/el1xr_opt.svg
    :target: https://badge.fury.io/py/el1xr_opt
    :alt: PyPI

.. image:: https://img.shields.io/pypi/pyversions/el1xr_opt.svg
   :target: https://pypi.org/project/el1xr_opt/
   :alt: Python version

.. image:: https://github.com/EL1XR-dev/el1xr_opt/actions/workflows/python-package-conda.yml/badge.svg
   :target: https://github.com/EL1XR-dev/el1xr_opt/actions/workflows/python-package-conda.yml
   :alt: Test passing
   :width: 150

.. image:: https://readthedocs.org/projects/el1xr-opt/badge/?version=latest
   :target: https://el1xr-opt.readthedocs.io/en/latest/
   :alt: Docs passing

.. image:: https://app.codacy.com/project/badge/Grade/2b804a25f68749498c5207dcdd05ed67
   :target: https://app.codacy.com/gh/EL1XR-dev/el1xr_opt/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade
   :alt: Codacy Badge

.. image:: https://img.shields.io/pypi/dm/el1xr_opt.svg
   :target: https://pypi.org/project/el1xr_opt/
   :alt: Downloads

**Electricity for Low-carbon Integration and eXchange of Resources (EL1XR)**

**el1xr_opt** is the core optimisation engine of the `EL1XR-dev` ecosystem. It provides a powerful and flexible modelling framework for designing and analysing integrated, zero-carbon energy systems, with support for electricity, heat, hydrogen, and energy storage technologies.

----

🚀 Features
-----------

- Modular formulation for multi-vector energy systems
- Compatible with **deterministic, stochastic, and equilibrium** approaches
- Flexible temporal structure: hours, days, representative periods
- Built on `Pyomo <https://pyomo.readthedocs.io/en/stable/>`_
- Interfaces with ``EL1XR-data`` (datasets) and ``EL1XR-examples`` (notebooks)

----

📂 Structure
------------

- ``src/``: Core source code for the optimisation model.
- ``data/``: Sample case studies.
- ``docs/``: Documentation and formulation notes.
- ``tests/``: Validation and regression tests.

----

📦 Prerequisites
----------------

- **Python 3.12** or higher.
- A supported solver: **Gurobi, CBC, or CPLEX**. Make sure the solver is installed and accessible in your system's PATH.

----

🚀 Installation
---------------

There are two ways to install **el1xr_opt**:

**Option 1: Install from PyPI (Recommended)**

You can install the latest stable release from PyPI:

.. code-block:: bash

   pip install el1xr_opt

**Option 2: Install from Source (for Developers)**

If you want to work with the latest development version or contribute to the project, you can install it from the source:

1. Clone the repository:

.. code-block:: bash

   git clone https://github.com/EL1XR-dev/el1xr_opt.git
   cd el1xr_opt

2. Create and activate a virtual environment (recommended):

.. code-block:: bash

   python -m venv venv
   source venv/bin/activate  # On Windows use `venv\Scripts\activate`

3. Install the required Python packages:

.. code-block:: bash

   pip install -r requirements.txt

----

⚡ Quick Example
----------------

Run the included `Home1` example case with the following command from the root directory:

.. code-block:: bash

   python src/el1xr_opt/oM_Main.py --dir data --case Home1 --solver gurobi

This will run the optimization and save the results in the `data/Home1` directory.

----

Usage
-----

To run the optimisation model, use the ``oM_Main.py`` script from the ``src`` directory. If you run the script without arguments, it will prompt you for them interactively.

.. code-block:: bash

   python src/el1xr_opt/oM_Main.py --case <case_name> --solver <solver_name>

**Command-line Arguments**

- ``--dir``: Directory containing the case data. For the sample cases, this would be `data`.
- ``--case``: Name of the case to run (e.g., ``Home1``). Defaults to `Home1`.
- ``--solver``: Solver to use (e.g., ``gurobi``, ``cbc``, ``cplex``). Defaults to `gurobi`.
- ``--date``: Model run date in "YYYY-MM-DD HH:MM:SS" format. Defaults to the current time.
- ``--rawresults``: Save raw results (`True`/`False`). Defaults to `False`.
- ``--plots``: Generate plots (`True`/`False`). Defaults to `False`.

----

🤝 Contributing
---------------

Contributions are welcome! If you want to contribute to **el1xr_opt**, please follow these steps:

1. Fork the repository.
2. Create a new branch for your feature or bug fix.
3. Make your changes and commit them with a clear message.
4. Push your changes to your fork.
5. Create a pull request to the ``main`` branch of this repository.

----

📄 License
----------

This project is licensed under the terms of the `GNU General Public License v3.0 <LICENSE>`_.

