GreenLight-Sim 0.1.0
Greenhouse Simulation and Optimization Toolkit
Requires Python: >=3.8


## GreenLight API Documentation

This GreenLight Python Package is an unofficial Python version, the the original MATLAB version developed by **[David Katzin](https://github.com/davkat1/GreenLight)** can be found here.

GreenLight is a Python package that provides a modeling framework for simulating greenhouse environments. The package is designed to assist researchers and practitioners in understanding and optimizing greenhouse performance in terms of energy consumption, light distribution, and crop yield.

---

## Features

The GreenLight Python Package offers a significant improvement in speed for **short time intervals** (i.e., 5 minutes, 1 hour, or 1 day) of greenhouse time settings. In fact, the Python version runs **5 ~ 10 times faster** than the original MATLAB version and up to 100 times faster than the Python interface, depending on device configuration. This makes it an ideal choice for reinforcement learning applications and similar scenarios.

---
## Usage

To use the GreenLight package, start by importing the `GreenLightModel` class from the `green_light_model` module:

```python
from greenlight import GreenLightModel
```

### Basic Usage:
```
from greenlight import GreenLightModel
import time as tm

if __name__ == "__main__":
    # Set the start time
    startTime = tm.time()

    # Initialize the model, set the season length to 5 minutes, and the weather input to Beijing
    model = GreenLightModel(season_length=1 / 24 / 6, weatherInput="bei")

    # Set the parameters to replace the default parameters,
    # more parameters can be found in the greenlight/set_gl_params.py file
    gl_params = {
        "p": {
            "tSpDay": 18.5,
            "tSpNight": 21.5,
        }
    }

    # Run the model， gl is the simulation results
    gl = model.run_model(gl_params)
    
    endTime = tm.time()
    totalTime = endTime - startTime
    print(f"Total time for 1 simulation: {totalTime} seconds")

```

You can then analyze and visualize the results using the functions provided in the `result_analysis` folder:

### Result Analysis:

```
import greenlight
from greenlight import (
    GreenLightModel,
    calculate_energy_consumption,
    energy_analysis,
    energy_yield_analysis,
    plot_green_light,
)

if __name__ == "__main__":

    # Initialize the model, set the season length to 5 minutes, and the weather input to Beijing, 1/24/6 means 5 minutes.
    model = GreenLightModel(season_length=1 / 24 / 6, weatherInput="bei")

    # Set the parameters to replace the default parameters,
    # more parameters can be found in the greenlight/set_gl_params.py file
    gl_params = {
        "p": {
            "tSpDay": 18.5,
            "tSpNight": 21.5,
        }
    }

    # Run the model， gl is the simulation results
    gl = model.run_model(gl_params)
    

    # Based on the simulation results, calculate the energy consumption of the lamps, boilers, and CO2
    # Energy consumption of the lamps [MJ m^{-2}]
    lampIn = calculate_energy_consumption(gl, "qLampIn", "qIntLampIn")

    # Energy consumption of the boiler, boilIn [MJ m^{-2}]
    boilIn = calculate_energy_consumption(gl, "hBoilPipe", "hBoilGroPipe")

    # CO2 Use,co2inj,kg/m2
    co2inj = calculate_energy_consumption(gl, "mcExtAir")

    # Energy_analysis
    (
        sunIn,
        heatIn,
        transp,
        soilOut,
        ventOut,
        firOut,
        lampIn,
        convOut,
        lampCool,
        balance,
    ) = energy_analysis(gl, True)

    # Energy yield analysis
    (
        lampIn,
        boilIn,
        hhIn,
        parSun,
        parLamps,
        yield_fw,
        efficiency,
    ) = energy_yield_analysis(gl, True)

    # Plot the simulation results
    plot_green_light(gl)

```

---

## Result comparsions with Matlab version
 
 - ### Python version plots and data 
 ![](data/outputs/16825554909302.jpg)

- ### Matlab version plots

![](data/outputs/16825558618150.jpg)

- ### Python results
    Energy consumption of the lamps: 0.02 MJ m^-2
    Energy consumption of the boiler: 0.08896825924555489 MJ m^-2
    CO2 Use: 0.0015428571428571423 kg m^-2

- ### Matlab results
    Energy consumption of the lamps: 0.02 MJ m^{-2}
    Energy consumption of the boiler: 0.088974 MJ m^{-2}
    CO2 Use: 0.0015429 kg m^{-2}

---

## Known Issues

In some cases, there may be a value overflow, especially when the number of days is long or when certain temperature settings are used. Additionally, this issue may result in significant discrepancies from the results of the original Matlab version. This issue is currently being investigated.

- Value overflow errors may occur when certain temperature settings are used, such as when tSpDay is 5.9 and tSpNight is 29.9 with a season_length of 1, resulting in a RuntimeWarning. However, in other cases with the same temperature settings, such as, when tSpDay is 5.9, tSpNight = 29.9 , season_length is 1, no warning may be issued, and the system appears to be functioning correctly.

- It is worth noting that the occurrence of value overflow errors tends to increase with longer season_length settings. In general, the system produces accurate results for short-term durations of 1 day or less, without any error messages.


### Error example:

```
# Initialize the model, set the season length to 5 minutes, and the weather input to Beijing
    model = GreenLightModel(season_length=1, weatherInput="bei")

    # Set the parameters to replace the default parameters,
    gl_params = {
        "p": {
            "tSpDay": 5.9,
            "tSpNight":29.9,
        }
    }

```

---
## Folder Structure

```markdown

greenlight/
│   __init__.py
│   green_light_model.py
├───service_functions/
│   │   rh2vapor_dens.py
│   │   make_artificial_input.py
│   │   vapor_dens2pres.py
│   │   funcs.py
│   │   co2_dens2ppm.py
│   │   vp2dens.py
│   │   co2_ppm2dens.py
├───create_green_light_model/
│   │   create_green_light_model.py
│   │   ode.py
│   │   set_gl_init.py
│   │   set_gl_control.py
│   │   set_dep_params.py
│   │   set_gl_control_init.py
│   │   set_params4ha_world_comparison.py
│   │   set_gl_odes.py
│   │   set_gl_states.py
│   │   set_gl_input.py
│   │   set_default_lamp_params.py
│   │   set_gl_params.py
│   │   set_gl_time.py
│   │   set_gl_aux.py
│   │   change_res.py
├───result_analysis/
│   │   energy_analysis.py
│   │   plot_green_light.py
│   │   energy_yield_analysis.py
└───data/some data files

    
```
---
## File Descriptions 
- `green_light_model.py`: Contains the GreenLightModel class, which is used to create model instances. 
- `service_functions/`: A folder containing general use functions. 
    - `rh2vapor_dens.py`: Converts relative humidity (in %) to vapor density (in kg{H2O} m^{-3}). 
    - `make_artificial_input.py`: Creates an artificial dataset to use as input for a GreenLight model. 
    - `vapor_dens2pres.py`: Converts vapor density to vapor pressure for given temperature and vapor density values. 
    - `funcs.py`: Contains utility functions required by other functions in the package. 
    - `co2_dens2ppm.py`: Converts CO2 density to ppm. 
    - `vp2dens.py`: Converts vapor pressure to vapor density. 
    - `co2_ppm2dens.py`: Converts CO2 in ppm to density. 
- `create_green_light_model/`: A folder containing core functionality for creating and working with GreenLight model instances. 
    - `create_green_light_model.py`: Main function for creating a GreenLight model instance. 
    - `ode.py`: Solves a system of ODEs. 
    - `set_gl_init.py`: Sets the initial values for the GreenLight model. 
    - `set_gl_control.py`: Sets the controls. 
    - `set_dep_params.py`: Sets the parameters according to the Vanthoor model. 
    - `set_gl_control_init.py`: Sets control variables for the greenhouse model. 
    - `set_params4ha_world_comparison.py`: Sets the parameters according to a modern 4 ha greenhouse. 
    - `set_gl_odes.py`: Sets the ODEs for x. 
    - `set_gl_states.py`: Sets initial gl states. 
    - `set_gl_input.py`: Sets inputs for a GreenLight model instance. 
    - `set_default_lamp_params.py`: Sets default settings for the lamp type in the GreenLight model. 
    - `set_gl_params.py`: Sets parameters - p for a GreenLight model based on the electronic appendices - of Vanthoor (2011). 
    - `set_gl_time.py`: Sets the time phase for a GreenLight greenhouse model. 
    - `set_gl_aux.py`: Sets auxiliary states for the GreenLight greenhouse model. 
    - `change_res.py`: Changes the resolution of the GreenLight model solution by interpolating the solution at a different time step. 
- `result_analysis/`: A folder containing functions for analyzing and visualizing the results of GreenLight simulations. 
    - `energy_analysis.py`: Calculates the energy consumption for each component of the model. 
    - `plot_green_light.py`: Plots commonly used graphs to visualize model results. 
    - `energy_yield_analysis.py`: Returns the resulting energy use, light above the canopy, yield, and efficiency of a GreenLight simulation.


---

## References

David Katzin, Simon van Mourik, Frank Kempkes, and Eldert J. Van Henten. 2020. “GreenLight - An Open Source Model for Greenhouses with Supplemental Lighting: Evaluation of Heat Requirements under LED and HPS Lamps.” Biosystems Engineering 194: 61–81. https://doi.org/10.1016/j.biosystemseng.2020.03.010