Metadata-Version: 2.1
Name: mosaik-pvgis
Version: 1.2.1
Summary: PVGIS Simulator for Mosaik
License: LICENSE
Author: Danila Valko
Author-email: mosaik@offis.de
Requires-Python: >=3.9,<4.0
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: Requests (>=2.31.0,<3.0.0)
Requires-Dist: arrow (>=1.3.0,<2.0.0)
Requires-Dist: faas_cache_dict (>=0.2.7,<0.3.0)
Requires-Dist: filelock (>=3.6.0,<4.0.0)
Requires-Dist: mosaik (>=3.2.0,<4.0.0)
Requires-Dist: mosaik-api-v3 (>=3.0.7,<4.0.0)
Requires-Dist: numpy (>=1.26.1,<2.0.0)
Requires-Dist: pandas (>=2.1.2,<3.0.0)
Requires-Dist: tqdm (>=4.66.1,<5.0.0)
Description-Content-Type: text/x-rst

============
mosaik-pvgis
============

This component simulates PV power output based on `PVGIS <https://re.jrc.ec.europa.eu/>`_ (Photovoltaic Geographical Information System) photovoltaic performance data (the data is free to use).
PVGIS provides information for any location in Europe and Africa, as well as a large part of Asia and America.

The PV simulator does not require any input, the only need to configure the PV system, geographical location and select an available reference year.

Since PVGIS only provides `hourly data <https://joint-research-centre.ec.europa.eu/photovoltaic-geographical-information-system-pvgis/pvgis-tools/hourly-radiation_en/>`_, any other step_size causes the data to be aggregated or splitted accordingly. If the step_size is less than an hour, it splits the value equally.

PV output data:

* P[MW] - active power produced

PV system input data:

* scale_factor - multiplies output [coef], might be used as a contol signal

Configuration:

* scale_factor [coef] - multiplies power production once model is created, 1 is equal to 1 kW peak power installed
* latitude [grad]
* longitude [grad]
* slope [grad] - inclination angle for the fixed plane
* azimuth [grad] - orientation angle for the fixed plane
* optimal_angle - if True, calculates and uses an optimal slope
* optimal_both - if True, calculates and uses an optimal slope and azimuth
* system_loss [%] - system inefficiency
* pvtech - PV technology: "CIS" (defaul), "crystSi", "CdTe", "Unknown"
* database - solar radiation `database <https://joint-research-centre.ec.europa.eu/photovoltaic-geographical-information-system-pvgis/getting-started-pvgis/pvgis-user-manual_en#ref-3-choosing-solar-radiation-database/>`_, PVGIS-SARAH2, PVGIS-NSRDB, PVGIS-ERA5, PVGIS-SARAH (default)
* datayear - reference year from database

An example scenario is located in the ´demo´ folder.

Other options
=============
Please pay attention to the input data. If you want to use only Direct Normal Irradiance input data as part of the co-simulation, 
then *mosaik-pv* is suitable, if you want to use full weather information (global irradiance, wind speed, air temperature and pressure) then *mosaik-pvlib* is suitable. 
If you are satisfied with historical performance estimates for a particular location or have no other input data, 
then *mosaik-pvgis* is the best solution which is based on PVGIS performance data.

Installation
=============

::

    pip install mosaik-pvgis



If you don't want to install this through PyPI, you can use pip to install the requirements.txt file::

    pip install -r requirements.txt

* To use this, you have to install at least version 3.2.0 of `mosaik <https://mosaik.offis.de/>`_.
* It is recommended, to use the *mosaik-csv* library to export the results.

How to Use
==========
Specify simulators configurations within your scenario script::

    SIM_CONFIG = {
        'PVSim': {
            'python': 'mosaik_components.pv.pvgis_simulator:PVGISSimulator'
        },
        'CSV_writer': {
            'python': 'mosaik_csv_writer:CSVWriter',
        },
        ...
    }

Initialize the PV-system::
   
    # Create PV system with certain configuration
    PVSIM_PARAMS = {
        'start_date' : START,
        'cache_dir' : './', # it caches PVGIS API requests
        'verbose' : True, # print PVGIS parameters and requests
    }
    pv_sim = world.start(
                    "PVSim",
                    step_size=STEP_SIZE,
                    sim_params=PVSIM_PARAMS,
                )

Instantiate model entities::

    PVMODEL_PARAMS = {
        'scale_factor' : 1000, # multiplies power production, 1 is equal to 1 kW peak power installed
        'lat' : 52.373, 
        'lon' : 9.738,
        'slope' : 0, # default value,
        'azimuth' : 0, # default value,
        'optimal_angle' : True, # calculate and use an optimal slope
        'optimal_both' : False, # calculate and use an optimal slope and azimuth
        'pvtech' : 'CIS', # default value,
        'system_loss' : 14, # default value,
        'database' : 'PVGIS-SARAH3', # default value,
        'datayear' : 2016, # default value,
    }
    pv_model = pv_sim.PVSim.create(1, **PVMODEL_PARAMS)

Connect with PV-simulator::

    world.connect(
                        pv_model[0],
                        csv_writer,
                        'P[MW]',
                    )

    world.run(until=END)


Notes
=====
The simulator configuration can be specified with the `sim_params` parameter in world.start:

* cache_dir : './' - if not False, a local dir and file are used to store PVGIS API requests (may cause some problems in case of lack of space or restrictions on file discriptors)
* verbose : True - output PVGIS API requests to stdout
* gen_neg : False - if True, multiplies output power by (-1)

Changelog
=========

1.2.1 - 2024-10-04
------------------

- PVGIS API update
- Minor changes

1.2 - 2024-02-13
------------------

- Control signal and gen_neg parameter are added
- Minor changes

1.0 - 2024-01-11
------------------

- Restructured as a mosaik component
- Readme and examples added
- Initial release of version implemented by Danila Valko

Authors
=======

The adapter was initially developed by Danila Valko.

