ChaProEV 1.2.7__tar.gz → 1.2.8__tar.gz

{chaproev-1.2.7 → chaproev-1.2.8}/.gitignore

@@ -11,4 +11,5 @@ reference_run/
 reference_run_prev/
 reference_run_previous/
 non-road-output/
+test_outputs/
 

{chaproev-1.2.7/src/ChaProEV.egg-info → chaproev-1.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ChaProEV
-Version: 1.2.7
+Version: 1.2.8
 Summary: ChaProEV: Charging Profiles of Electric Vehicles
 Author-email: Omar Usmani <Omar.Usmani@TNO.nl>
 Project-URL: Homepage, https://github.com/TNO/ChaProEV
@@ -37,8 +37,7 @@ This repository contains the ChaProEV (Charging Profiles of Electric Vehicles)
 model.
 
 ## Status
-The ChaProEV model is currently released and useable. This version
-has been used in projects and can be used in future projects.
+The ChaProEV model is under construction and not yet ready for use.
 Please contact the authors below if you have questions or requests to get
 model runs at some point.
 

chaproev-1.2.8/README.md

@@ -0,0 +1,160 @@
+# **ChaProEV**
+
+
+
+
+<center>
+<img src=MOPO_logo_chaproev.svg>
+</center>
+
+
+
+This repository contains the ChaProEV (Charging Profiles of Electric Vehicles)
+model.
+
+## Status
+The ChaProEV model is under construction and not yet ready for use.
+Please contact the authors below if you have questions or requests to get
+model runs at some point.
+
+## Authors and contact
+Omar Usmani (Omar.Usmani@TNO.nl)
+
+
+## Licence
+
+ChaProEV is released under the Apache 2.0 license.
+All accompanying documentation and manual are released under the 
+Creative Commons BY-SA 4.0 license.
+
+## Requirements
+
+
+(See requirements.txt file for versions (corresponding to Python 3.11.1, which
+is the version used for developing and testing the model))
+
+## Installation and use
+
+
+You can install ChaProEV with pip:
+```
+pip install ChaProEV
+```
+And then import ChaProEV in your code.
+You can of course use the various functions of ChaProEV, but the general
+use case is to run the model and focus on defining your case through the
+scenarios and their variants.
+In that case, the only piece of code you need is as follows (you just need
+to put the name of the folder where you put your case scenarios instead of the
+'Mopo'  example).
+```python
+from ChaProEV import ChaProEV
+
+if __name__ == '__main__':
+    case_name: str = 'Mopo'
+    ChaProEV.run_ChaProEV(case_name)
+```
+If you installed ChaProEV with pip, then the requirements
+should be installed as well (see requirements.txt file if you have issues
+or use the contact below).
+To run the model, you need to put a ChaProEV.toml configuration
+in the folder where you run your model. You also need to have at least one scenario in your scenario/case_name (e.g. scenario/Mopo) folder. A
+If you want to create varaints, then you need to add a case.toml (e.g. Mopo.toml) file in the variants folder and put a variant file in the variants/case (e.g. variants/Mopo) folder. 
+If you want to compute fleet-level values and/or do a car owndriveway/street charging split, you need to put some files in the input/case (e.g. input/Mopo) folder.
+You can use the examples provided in this repository. You can also
+unzip [this file](https://github.com/TNO/ChaProEV/blob/main/ChaProEV_test_case_configuration_files.zip)
+into your working folder and use 'test_case'  as your case name:
+```python
+from ChaProEV import ChaProEV
+
+if __name__ == '__main__':
+    case_name: str = 'test_case'
+    ChaProEV.run_ChaProEV(case_name)
+```
+
+
+
+For examples of running ChaProEV and more configuration files,
+you can visit the [ChaProEV runs repository](https://github.com/TNO/ChaProEV_runs).
+
+## General approach and structure
+- Split into scenarios, modules/computations, output profiles
+- USer can define a case (series of scenarios) without having to do anything
+with the code. They just need to edit/add scenarios and variants.
+<center>
+<img src=ChaProEV_workflow.png>
+</center>
+
+## Documentation
+
+The docmentation can be found [here](https://tno.github.io/ChaProEV/)
+## **Context, goals, and future developments**
+
+### **Driver**
+The primary driver for the publication and development of ChaProEV in this
+repository is the participation in the 
+[Mopo](https://www.tools-for-energy-system-modelling.org/) project (funded from 
+European Climate, 
+Infrastructure and Environment Executive Agency under the European Union’s 
+HORIZON Research and Innovation Actions under grant agreement N°101095998).
+
+### **Goal**
+The main goal of providing this repository is transparency regarding the 
+assumptions and computations of the ChaProEV model.
+
+### **Uses outside Mopo**
+
+#### **Prior to Mopo**
+
+1. [Afspraken maken: 
+Van data tot 
+informatie
+Informatiebehoeften, datastandaarden en 
+protocollen voor provinciale 
+systeemstudies – Deel II technische 
+rapportage. Nina Voulis, Joeri Vendrik, Reinier van der Veen, Alexander Wirtz, Michiel Haan, Charlotte von Meijenfeldt, 
+Edwin Matthijssen, Sebastiaan Hers, Ewoud Werkman (CE Delft, TNO, Quintel), April 2021](https://cedelft.eu/wp-content/uploads/sites/2/2021/07/CE_Delft_200227_Afspraken_maken_Van_data_tot_informatie_Deel-2.pdf) where a previous version of ChaProEV was used to provide charging profiles of electric vehicles at the province level (for the Dutch proivinces of North Holland and Limburg)
+
+2. [Elektrisch rijden personenauto's & logistiek: Trends en impact op het elektriciteitssyteem. Hein de Wilde, Charlotte Smit, Omar Usmani, Sebastiaan Hers (TNO), Marieke Nauta (PBL), August 2022](https://publications.tno.nl/publication/34640002/AVDCKb/TNO-2022-P11511.pdf) where a previous version of ChaProEV was used to identify potential moments where charging electric cars could result in local (i.e. neighbourhood/transformer level) network issues and see if these issues could be solved.
+
+3. [Verlagen van lokale impact laden elektrisch vervoer: De waarde en haalbarheid van potentiële oplossingen, Charlotte Smit, Hein de Wilde, Richard Westerga, Omar Usmani, Sebastiaan Hers, TNO M12721, December 2022](https://energy.nl/wp-content/uploads/kip-local-impact-ev-charging-final-1.2.pdf) where a previous version of ChaProEV was used to identify and quantify potential solutions to potential local (i.e. neighbourhood/transformer level) issues due to a possible large-scale adoption of electric cars (with illustrative examples for neighbourhoods in ihe cities of Amsterdam and Lelystad).
+
+4. [TRADE-RES](https://traderes.eu/). A previous version of ChaProEV was used to generate reference charging profiles for a number of European countries, based on statistical differences per country. 
+Results are in the [TRADE-RES scenario database](https://zenodo.org/records/10829706)
+
+
+
+#### **After/during Mopo**
+1. I.S. Jimenez, D. Ribó-Pérez, M. Cvetkovic, J. Kochems, C. Schimeczek,
+L. de Vries,[Can an energy only market enable resource ade-
+quacy in a decarbonized power system? a co-simulation with
+two agent-based-models](https://www.sciencedirect.com/science/article/pii/S0306261924000783)
+Applied Energy 360 (2024) 122695
+2. S. Johanndeiter, N. Helistö, J. Kiviluoma, V. Bertsch,  [Price formation
+and intersectoral distributional eects in a fully decarbonised european
+electricity market](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=48874423)
+3. Sanchez Jimenez, Ingrid and Johanndeiter, Silke and de Vries, Laurens, Capacity Remuneration Mechanisms for Power Systems in Transition. Available at SSRN: https://ssrn.com/abstract=5196543 or http://dx.doi.org/10.2139/ssrn.5196543
+
+
+#### **Future**
+The ChaProEV will be used in other projects that will be listed here, if deemed
+relevant and apprpriate within the context of these projects.
+
+
+
+## Acknowledgments
+&nbsp;
+<hr>
+<center>
+<table width=500px frame="none">
+<tr>
+<td valign="middle" width=100px>
+<img src=eu-emblem-low-res.jpg alt="EU emblem" width=100%></td>
+<img src=MOPO_logo_main.svg width = 25%>
+<td valign="middle">This project was partly develop under funding from the 
+European Climate, 
+Infrastructure and Environment Executive Agency under the European Union’s 
+HORIZON Research and Innovation Actions under grant agreement N°101095998.</td>
+<tr>
+</table>
+</center>

chaproev-1.2.8/docs/define.md

@@ -0,0 +1,183 @@
+
+# Classes
+
+## Leg
+This class defines the legs and their properties, from a scenario
+file that contains a list of instances and their properties.
+Legs are point-to-point vehicle movements (i.e. movements where
+the vehicle goes from a start location and ends/stops at an end location).
+
+### Parameters
+The parameters of a leg are:
+
+1. **Name:** The name of the leg
+2. **Vehicle:** The vehicle that runs the leg. If this does not correspond
+to the [scenario vehicle name](scenario.md#vehicle-name), then the leg is not
+declared.  Note that when running a
+scenario, you select one vehicle, so this is in principle not necessary.
+The reason for having this is to allow the user to copy the baseline file
+and keep the location definitions that are not used for this scenario but
+might be so for another, thereby reducing the need for changes between
+scenarios.
+3. **Distance:** The distance driven during the leg (in kilometers)
+4. **Duration:** How long it takes to drive the leg (in hours)
+5. **Hour in day factors:** These factors add a correction to the vehicle 
+consumption that depend on the hour in day (the first is for 00:00 to 00:59,
+last for 23:00 to 23:59). Note that these are actual hours,
+not hours in the user day (which can start and end at other moments than
+midnight). This is used to take into account things like traffic jams.
+The default value is 1. ***This factor is a placeholder and is currently not
+in use.***
+
+## Location
+This class defines the locations where the vehicles are
+and their properties, from a scenario
+file that contains a list of instances and their proper.
+
+### Parameters
+
+The parameters of a location are:
+
+1. **Name**: The name of the location.
+2. **Vehicle:** The vehicle that uses the location. If this does not correspond
+to the [scenario vehicle name](scenario.md#vehicle-name), then the trip is not
+declared.  Note that when running a
+scenario, you select one vehicle, so this is in principle not necessary.
+The reason for having this is to allow the user to copy the baseline file
+and keep the location definitions that are not used for this scenario but
+might be so for another, thereby reducing the need for changes between
+scenarios.
+3. **Connectivity:** A value between 0 and 1 (0% to 100%) that tells the
+probability that a vehicle parked at this location is connected to a
+charger.
+4. **Charging power:** The (peak) charging power of the charger at this
+location (in kW).
+5. **Charger efficiency:** A value between 0 and 1 (0% to 100%) that tells how
+much of the power drawn from the network is delivered to the battery of the
+vehicle.
+6. **Latitude:** The latitude of the location. ***This factor is a placeholder
+and is currently not in use.***
+7. **Longitude:** The longitude of the location. ***This factor is a 
+placeholder and is currently not in use.***
+8. **Base charging price:** The base/reference (i.e. before
+flexibility/temporal changes) charging price at this location, in €/kWh.
+***This factor is a placeholder and is currently not in use.***
+9. **Charging desirability:** A value between 0 and 1 (0% to 100%) that tells
+how much the users like to charge at this location.
+***This factor is a placeholder and is currently not in use.***
+10. **Percentage in location at run start:** A value between 0 and 1
+(0% to 100%) that tells which percentage of the vehicles start the run there.
+This is used if we will that in directly instead of computing it. The decision
+t use this is controlled by the compute_start_location_split parameter in
+the [mobility](mobility.md#module-parameters) module.
+
+## Trip
+
+This class defines the trips and their properties, from a scenario
+file that contains a list of instances and their properties.
+Trips are collections of legs that take place on a given day.
+Note that this day does not necessarily start (and end) at midnight,
+but can start (and end) at an hour that is more logical/significant for the
+vehicle user (it could for example be 05:00 for car drivers).
+This [day start hour](scenario.md#day_start_hour)
+parameter is universal for all trips
+This value is set in the scenario files.
+
+### Parameters
+1. **Name**: The name of the trip.
+2. **Vehicle:** The vehicle that does the trip. If this does not correspond
+to the [scenario vehicle name](scenario.md#vehicle-name), then the trip is not
+declared. Note that when running 
+a scenario, you select one vehicle, so this is in principle not necessary.
+The reason for having this is to allow the user to copy the baseline file
+and keep the trip definitions that are not used for this scenario but
+might be so for another, thereby reducing the need for changes between
+scenarios.
+3. **Legs:** A list of the legs in the trip.
+4. **Time between legs:** A list of the time spent at the arrival locations
+between each leg (in hours).
+5. **Percentage station users:**A value between 0 and 1
+(0% to 100%) that tells us which percentage of users use fast charging
+stations.
+***This factor is a placeholder and is currently not in use.***
+6. **Start probabilities:** A list of values between 0 and 1 (0%-100%) adding
+up to 1/100% that tells us what the probability of starting the trip is at
+a given hour. Note that the hours start at 
+ [day start hour](scenario.md#day_start_hour), not at
+midnight.
+7. **Repeated sequence:** A list of repeated legs 
+(which should follow each other) that form a repeated sequence.
+8. **Repetition amounts:** How often
+the repeated sequence is repeated. This is a list, with one value per leg
+repetition (the nth element corresponds to the nth appearance of
+the sequence in the leg list).
+9. **Time between repetitions:** The time between repetitions of each
+repeated sequence (in hours). This is a list, with one value per leg
+repetition (the nth element corresponds to the nth appearance of
+the sequence in the leg list).
+
+
+### Mobility matrix
+
+The main aim of the trip initialization/declaration is to create a mobility
+matrix for the trip.
+This mobility matrix has, for all combinations of possible start and end 
+locations (i.e.
+locations connected by a leg in the trip) and for each hour in day number
+(starting at the [day start hour](scenario.md#day_start_hour)), the following
+quantities:
+1. **Duration:** The duration (in hours) of a leg between the start location
+and the end location.
+2. **Distance:** The distance (in kilometers) of a leg between the start 
+location.
+3. **Weighted distance:** The weighted distance (in kilometers) of a leg 
+between the start location and the end location. This corresponds to using
+different [road types](scenario.md#road_types), with given
+[weights](scenario.md#weights) and given [mixes](scenario.md#mix) to account
+for the fact that vehicles consume more on some road types.
+4. **Departures amount**: The chance that a vehicle, in a given hour, leaves
+the start location,
+going to the end location (amount and chance are equivalent
+here, as we compute on an individual vehicle basis).
+5. **Departures kilometers:** The kilometers driven by vehicles leaving the
+start location at a given hour and going to the end location. This is given
+by the departures amount times the distance.
+6. **Departures weighted kilometers:** The weighted (by road type) kilometers
+driven by vehicles leaving the start location at a given hour and going to the 
+end location. This is given
+by the departures amount times the weighted distance.
+7. **Arrivals amount**: The chance that a vehicle, in a given hour,
+ arrives to the end
+location,
+having started the start location (amount and chance are equivalent
+here, as we compute on an individual vehicle basis).
+8. **Arrivals kilometers:** The kilometers driven by vehicles arriving to the
+end location at a given hour, having started at the start location. 
+This is given
+by the arrivals amount times the distance.
+9. **Arrivals weighted kilometers:** The weighted (by road type) kilometers
+driven by vehicles arriving to the end location at a given hour, having 
+started at the start location. This is given
+by the arrivals amount times the weighted distance.
+
+The model also produces a version of this mobility matrix for the whole
+run (which is essentially a copy of the above matrix). This run
+mobility matrix is the mobility matrix if the trip had a probability of 1
+for the whole run.
+
+
+
+
+#### Leg repetitions
+
+Is repeat of leg or two legs????
+[0, 5, 5, 0]
+If next leg is also repeated/still has repeats left, then it is repeated after the leg
+in question
+so when putting a leg, check if it is repeated. If so, check if the next is repeated,
+until you have no repeats (or end the list). Add on of each repeated legs
+then number of repeats goes down by one and redo
+Have one trip per day type for non-cars
+
+Reference to day start hour
+cross-links with scenario

chaproev-1.2.8/docs/general_parameters.md

@@ -0,0 +1,153 @@
+# Purpose
+The purpose of the ChaProEV.toml file is to set parameters
+that are common for all your scenarios.
+This page describes the various parameters.
+You can use the navigation bar on the left to go directly to a group
+of parameters (or a given parameter).
+
+## variants
+The variants section of the configuration file sets parameters
+to create scenario [variants](variants.md) (see that page for
+details).
+
+### use_variants 
+Setting the use_variants parameters to true creates variants,
+while setting it to false skips variant creation althogether.
+
+### csv_version 
+
+Setting the csv_version to true parameters makes you use csv files
+to define your variants (in a folder within the variants folder: this
+folder needs to have the same name as your case). Setting it to false makes you use a toml file in the variants folder (case_name.toml).
+
+### use_years_in_profiles
+
+This is used to create different variants per year when doing 
+[car home own driveway and street parking splits](car_home_own_driveway_splits.md)
+
+
+
+
+## parallel_processing
+This parallel processing section of the configuration file sets parameters to manage the [parallel processing/multiprocessing](multiprocessing.md) of the model (which reduces the model run time, see link for details).
+
+### set_amount_of_processes 
+
+Set this as false if you want the amount of parallel processes to be determined by the model (via the [multiprocessing standard library of Python](https://docs.python.org/3/library/multiprocessing.html)). Set this to true if you want to set the amount of processes yourself.
+
+### amount_for_scenarios
+
+If you put true in set_amount_of_processes, provide a number of parallel processes here to run scenarios in parallel.
+
+### amount_for_pickle_saves 
+If you put true in set_amount_of_processes, provide a number of parallel processes here to save the pickle output saves to other formats in parallel (see [writing module](writing.md) for details).
+
+## interim_files
+This concerns parameters for saving intermediary results to files.
+
+### pickle
+Set this to true to save interim results to pickle files.
+Set this to false not to do this.
+### consumption_tables_frequencies
+ Provide a list of consumption
+tables frequencies (see [consumption module](consumption.md)). The default is the following list ['hourly', 'daily', 'weekly', 'monthly', 'yearly']
+### save_consumption_table
+Provide a list of booleans (true or false) to save a given frequency to file (this list needs to have the same length as the above list): true save a file for that frequency and false does not.
+
+
+
+
+## profile_dataframe
+
+### headers
+### fleet_headers
+### do_fleet_tables
+### fleet_file_name
+
+## sessions_dataframe
+
+### properties
+### dataframe_headers
+### run_dataframe_headers
+### display_dataframe_headers
+### display_dataframe_index
+### fleet_display_dataframe_headers
+
+## plots
+### vehicle_temperature_efficiency
+#### style
+#### source_data_folder
+#### source_data_file 
+#### fit_color 
+#### fit_line_size
+#### geotab_data_color 
+#### geotab_data_size
+#### title_size 
+
+## files
+### input_root
+### output_root
+### groupfile_root
+
+### figures
+#### dpi
+#### outputs
+
+### dataframe_outputs
+
+
+## maps
+## map_data_folder
+## area_data_file_name
+## general_exclusion_codes
+## border_data_file_prefix
+## border_data_file_suffix
+## points_data_file_prefix
+## points_data_file_suffix
+## country_code_header
+## country_code_header_in_map_data
+## heat_bar_map
+
+## colors
+
+## color_bars
+
+## unit_conversions
+
+## numbers
+
+## consumption
+### energy_carriers
+### consumption_table_name
+### time_header
+### distance_header
+### fleet_distance_header
+### energy_carriers_consumption_names
+### fleet_energy_carriers_consumption_names
+
+
+## home_type
+### do_car_home_type_split
+### percentages_file
+### index_name
+### own_driveway_name
+### on_street_name
+### profiles_index
+### sessions_index
+### sessions_values_columns
+
+## sessions
+### produce
+### generate_profiles
+## standard_profiles
+### produce
+
+## progress_bars
+### display_scenario_run
+### scenario_run_description
+### display_saving_pool_run
+### saving_pool_run_description
+
+## discharge
+### no_discharge_efficiency_output
+### no_charge_efficiency_output

chaproev-1.2.8/docs/index.md

@@ -0,0 +1 @@
+# ChaProEV

chaproev-1.2.8/docs/mobility.md

@@ -0,0 +1,4 @@
+# Mobility
+
+
+## Module parameters