API¶

Truck Input Parameter¶

class carculator_truck.truck_input_parameters.TruckInputParameters(parameters: str | Path | list | None = None, extra: str | Path | list | None = None)¶

Array¶

carculator_utils.array.fill_xarray_from_input_parameters(input_parameters, sensitivity=False, scope=None)¶

Create an xarray labeled array from the sampled input parameters.

This function extracts the parameters’ names and values contained in the parameters attribute of the CarInputParameters class in car_input_parameters and insert them into a multi-dimensional numpy-like array from the xarray package (http://xarray.pydata.org/en/stable/).

Parameters:¶

sensitivity=False¶
input_parameters¶: Instance of the TruckInputParameters class

in truck_input_parameters. :returns: tuple, xarray.DataArray - tuple (size_dict, powertrain_dict, parameter_dict, year_dict) - array

Dimensions of array:

Vehicle size, e.g. “3.5t”, “7.5t”, etc. str.

Powertrain, e.g. “ICE-d”, “BEV”. str.

Year. int.

Samples.

Driving cycle¶

carculator_truck.driving_cycles.get_driving_cycle(size: list, name: str) → ndarray¶

Get driving cycle.

Parameters:¶

size: list¶: List of vehicle sizes.
name: str¶: The name of the driving cycle.

Returns:¶

ndarray() object

carculator_truck.driving_cycles.get_road_gradient(size: list, name: str) → ndarray¶

Get road gradient data.

Parameters:¶

size: list¶: List of vehicle sizes.
name: str¶: The name of the driving cycle.

Returns:¶

ndarray() object

Energy consumption¶

energy_consumption.py contains the class EnergyConsumption Model which exposes two methods: one for calculating the auxiliary energy needs, and another one for calculating the motive energy needs.

class carculator_utils.energy_consumption.EnergyConsumptionModel(vehicle_type: str, vehicle_size: list[str], powertrains: list[str], cycle: str | ndarray, gradient: str | ndarray, rho_air: float = 1.204, country: str = 'CH', ambient_temperature: float | ndarray | None = None, indoor_temperature: float | ndarray = 20)¶

Calculate energy consumption of a vehicle for a given driving_cycles and vehicle parameters.

Based on a selected driving_cycles, this class calculates the acceleration needed and provides two methods:

aux_energy_per_km() calculates the energy needed to power auxiliary services

motive_energy_per_km() calculates the energy needed to move the vehicle over 1 km

Acceleration is calculated as the difference between velocity at t_2 and velocity at t_0, divided by 2. See for example: http://www.unece.org/fileadmin/DAM/trans/doc/2012/wp29grpe/WLTP-DHC-12-07e.xls

Parameters:¶

cycle : np.ndarray¶: Driving cycle. Pandas Series of second-by-second speeds (km/h) or name (str)
rho_air : float¶: Mass per unit volume of air. Set to (1.225 kg/m3) by default.
gradient: str | ndarray¶: Road gradient per second of driving, in degrees.

None by default. Should be passed as an array of length equal to the length of the driving_cycles. :type gradient: numpy.ndarray

Variables:¶

rho_air : float¶: Mass per unit volume of air. Value of 1.204 at 23C (test temperature for WLTC).
velocity : numpy.ndarray: Time series of speed values, in meters per second.
acceleration: Time series of acceleration, calculated as

increment in velocity per interval of 1 second, in meter per second^2. :vartype acceleration: numpy.ndarray

Calculate energy used other than motive energy per km driven.

Parameters:¶

aux_power: DataArray | array¶: Total power needed for auxiliaries, heating, and cooling (W)
efficiency: DataArray | array¶: Efficiency of electricity generation (dimensionless, between 0.0 and 1.0). Battery electric vehicles should have efficiencies of one here, as we account for battery efficiencies elsewhere.

Returns:¶

total auxiliary energy in kJ/km

find_last_driving_second() → ndarray¶: Find the last second of the driving_cycles that is not zero.

Calculate energy used and recuperated for a given vehicle per km driven.

param driving_mass:

Mass of vehicle (kg)

param rr_coef:

Rolling resistance coefficient (dimensionless, between 0.0 and 1.0)

param drag_coef:

Aerodynamic drag coefficient (dimensionless, between 0.0 and 1.0)

param frontal_area:

Frontal area of vehicle (m2)

param sizes:

size classes of the vehicles

param electric_motor_power:

Electric motor power (watts). Optional.

returns:

net motive energy (in kJ/km)

Power to overcome rolling resistance is calculated by:

\[g v M C_{r}\]

where \(g\) is 9.81 (m/s2), \(v\) is velocity (m/s), \(M\) is mass (kg), and \(C_{r}\) is the rolling resistance coefficient (dimensionless).

Power to overcome air resistance is calculated by:

\[\]

rac{1}{2} ho_{air} v^{3} A C_{d}

where :math:`

ho_{air}` is 1.225 (kg/m3), \(v\) is velocity (m/s), \(A\) is frontal area (m2), and \(C_{d}\): is the aerodynamic drag coefficient (dimensionless).

carculator_utils.energy_consumption.get_country_temperature(country)¶: Retrieves mothly average temperature :type country: country for which to retrieve temperature values :return:

carculator_utils.energy_consumption.get_default_driving_cycle_name(vehicle_type) → str¶: Get the default driving_cycles name

Truck Model¶

class carculator_truck.model.TruckModel(array: DataArray, country='CH', cycle: None | str | ndarray = None, gradient: None | ndarray = None, energy_storage: None | dict = None, electric_utility_factor: float | None = None, drop_hybrids: bool = True, payload=None, annual_mileage=None, energy_target=None, energy_consumption: dict | None = None, engine_efficiency: dict | None = None, transmission_efficiency: dict | None = None, target_range: dict | None = None, target_mass: dict | None = None, power: dict | None = None, fuel_blend: dict | None = None, ambient_temperature: float | None = None, indoor_temperature: float = 20)¶

This class represents the entirety of the vehicles considered, with useful attributes, such as an array that stores all the vehicles parameters.

Variables:¶

array : xarray.DataArray¶: multidimensional numpy-like array that contains parameters’ value(s)
mappings : dict: Dictionary with names correspondence
ecm : coarse.energy_consumption.EnergyConsumptionModel: instance of EnergyConsumptionModel class for a given driving cycle

adjust_cost()¶: This method adjusts costs of energy storage over time, to correct for the overly optimistic linear interpolation between years.

calculate_cost_impacts(sensitivity=False, scope=None)¶

This method returns an array with cost values per vehicle-km, subdivided into the following groups:

Purchase
Maintenance
Component replacement
Energy
Total cost of ownership

Returns:¶: A xarray array with cost information per vehicle-km
Return type:¶: xarray.core.dataarray.DataArray

calculate_ttw_energy()¶: This method calculates the energy required to operate auxiliary services as well as to move the vehicle. The sum is stored under the parameter label “TtW energy” in self.array.

override_range()¶: Set storage size or range for each powertrain.

remove_energy_consumption_from_unavailable_vehicles()¶: This method sets the energy consumption of vehicles that are not available to zero.

set_all(electric_utility_factor: float | None = None)¶

This method runs a series of other methods to obtain the tank-to-wheel energy requirement, efficiency of the vehicle, costs, etc.

set_component_masses(), set_vehicle_masses() and set_power_parameters() and set_energy_stored_properties() relate to one another. powertrain_mass depends on power, curb_mass is affected by changes in powertrain_mass, combustion engine mass, electric engine mass. energy battery mass is influencedby the curb mass but also by the target range the truck has. power is also varying with curb_mass.

The current solution is to loop through the methods until the change in payload between two iterations is inferior to 0.1%. It is then assumed that the trucks are correctly sized.

Parameters:¶

electric_utility_factor: float | None = None¶: the share of km driven in battery-depleting mode over the required range autonomy

Returns:¶

Does not return anything. Modifies self.array in place.

set_battery_fuel_cell_replacements()¶

This method calculates the number of replacement batteries needed to match the vehicle lifetime. Given the chemistry used, the cycle life is known. Given the lifetime kilometers and the kilometers per charge, the number of charge cycles can be inferred.

If the battery lifetime surpasses the vehicle lifetime, 100% of the burden of the battery production is allocated to the vehicle. Also, the number of replacement is rounded up. This means that the entirety of the battery replacement is allocated to the vehicle (and not to its potential second life).

set_cargo_mass_and_annual_mileage()¶: Set the cargo mass and annual mileage of the vehicles.

set_costs()¶: Calculate the different cost types. :return:

set_electric_utility_factor(uf: float | None = None) → None¶: The electric utility factor is the share of km driven in battery-depleting mode over the required range autonomy. Scania’s PHEV tractor can drive 60 km in electric mode

set_energy_stored_properties()¶: First, fuel mass is defined. It is dependent on the range required. Then batteries are sized, depending on the range required and the energy consumption.

set_vehicle_masses()¶

Define curb mass, driving mass, and cargo mass.

curb mass is the mass of the vehicle and fuel, without people or cargo.
cargo mass is the mass of the cargo and passengers.
driving mass is the curb mass plus cargo mass.

Note

driving mass = cargo mass + driving mass

Noise Model¶

noise_emissions.py contains NoiseEmissionsModel which calculates noise emissions, in joules, given a driving_cycles and a powertrain type.

class carculator_utils.noise_emissions.NoiseEmissionsModel(velocity: DataArray, vehicle_type: str)¶

Calculate propulsion and rolling noise emissions for combustion, hybrid and electric vehicles, based on CNOSSOS model.

Parameters:¶

velocity : pandas.Series¶: Driving cycle. Pandas Series of second-by-second speeds (km/h) or name (str) of cycle e.g., “WLTC”,”WLTC 3.1”,”WLTC 3.2”,”WLTC 3.3”,”WLTC 3.4”,”CADC Urban”,”CADC Road”, “CADC Motorway”,”CADC Motorway 130”,”CADC”,”NEDC”.

get_sound_power_per_compartment() → ndarray¶

Calculate sound energy (in J/s) over the driving_cycles duration from sound power (in dB). The sound energy sums are further divided into geographical compartments: urban, suburban and rural, based on the profile of the driving_cycles.

Returns:¶: Sound energy (in Joules) per km driven, per geographical compartment.
Return type:¶: numpy.ndarray

propulsion_noise() → ndarray¶

Calculate noise from propulsion engine and gearbox. Model from CNOSSOS-EU project (http://publications.jrc.ec.europa.eu/repository/bitstream/JRC72550/cnossos-eu%20jrc%20reference%20report_final_on%20line%20version_10%20august%202012.pdf)

For electric cars, special coefficients are applied from (Pallas et al. 2016 )

Also, for electric cars, a warning signal of 56 dB is added when the car drives at 20 km/h or lower.

Returns:¶: A numpy array with propulsion noise (dB) for all 8 octaves, per second of driving_cycles
Return type:¶: numpy.array

rolling_noise() → ndarray¶

Calculate noise from rolling friction. Model from CNOSSOS-EU project (http://publications.jrc.ec.europa.eu/repository/bitstream/JRC72550/cnossos-eu%20jrc%20reference%20report_final_on%20line%20version_10%20august%202012.pdf)

Returns:¶: A numpy array with rolling noise (dB)

for each 8 octaves, per second of driving_cycles :rtype: numpy.array

carculator_utils.noise_emissions.get_noise_coefficients(filepath: Path) → None | DataArray¶

Noise coefficients extracted for vehicles from CNOSSOS-EU 2018 detailed by size, powertrain and EURO class for each octave.

Parameters:¶

filepath : Path¶: Path to the noise coefficients file.

Returns:¶

Noise coefficients.

Return type:¶

xr.DataArray

Hot pollutants emissions¶

hot_emissions.py contains HotEmissionModel which calculates fuel-related exhaust emissions.

class carculator_utils.hot_emissions.HotEmissionsModel(powertrains: array, sizes: array, velocity: ndarray, cycle_name: str, vehicle_type: str)¶

Calculate hot pollutants emissions based on HBEFA 4.1 data, function of fuel consumption for vehicles with a combustion engine.

Parameters:¶

cycle : pandas.Series: Driving cycle. Pandas Series of second-by-second speeds (km/h) or name (str) of cycle e.g., “WLTC”,”WLTC 3.1”,”WLTC 3.2”,”WLTC 3.3”,”WLTC 3.4”,”CADC Urban”,”CADC Road”, “CADC Motorway”,”CADC Motorway 130”,”CADC”,”NEDC”.

get_hot_emissions(euro_class: list[int], lifetime_km: DataArray, energy_consumption: DataArray, yearly_km: DataArray) → DataArray¶

Calculate hot pollutants emissions given a powertrain type (i.e., diesel, petrol, CNG) and a EURO pollution class, per air sub-compartment (i.e., urban, suburban and rural). Note that Nh3 and N2O emissions do not depend on the speed level. For those, average values observed across different traffic situations are used instead. Also includes cold start emissions. Cold start emissions are also given by HBEFA 4.1 and expressed in given in g/start. Cold start emissions are divided by the average trip length in Europe (20 km), to normalize them per km.

The emission sums are further divided into air compartments: urban, suburban and rural.

urban: from 0 to 50 km/k

suburban: from 51 km/h to 80 km/h

rural: above 80 km/h

Parameters:¶

powertrain_type: “diesel”, “petrol” or “CNG”
euro_class: list[int]¶: integer, corresponding to the EURO pollution class
energy_consumption: DataArray¶: tank-to-wheel energy consumption for each second of the driving_cycles
yearly_km: DataArray¶: annual mileage, to calculate cold start emissions

Returns:¶

Pollutants emission per km driven, per air compartment.

carculator_utils.hot_emissions.get_emission_factors(filepath) → [Any, None]¶: Hot emissions factors extracted for passenger cars from HBEFA 4.1 detailed by size, powertrain and EURO class for each substance.

carculator_utils.hot_emissions.get_mileage_degradation_factor(lifetime_km: DataArray, euro_class: list[int], powertrains: list[str], vehicle_type: str) → [<class 'xarray.core.dataarray.DataArray'>, None]¶: Catalyst degrade overtime, leading to increased emissions of CO, HC and NOX. We apply a correction factor from HBEFA 4.1 to reflect this. :return:

Inventory calculation¶

inventory.py contains Inventory which provides all methods to solve inventories.

class carculator_truck.inventory.InventoryTruck(vm, background_configuration: dict | None = None, scenario: str = 'SSP2-NPi', method: str = 'recipe', indicator: str = 'midpoint', functional_unit: str = 'vkm')¶

Build and solve the inventory for results characterization and inventory export

fill_in_A_matrix()¶

Fill-in the A matrix. Does not return anything. Modifies in place. Shape of the A matrix (values, products, activities).

array from CarModel class

Inventory export¶

export.py contains the class Export, which offers methods to export the inventories in different formats.

class carculator_utils.export.ExportInventory(array, vehicle_model, indices, db_name='carculator_utils export')¶

Export the inventory to various formats

rename_vehicles() → None¶: Rename powertrain acronyms to full length descriptive terms

write_bw2_lci(ecoinvent_version: str, directory: str | None = None, filename: str | None = None, export_format: str = 'file') → bytes | str | LCIImporter¶

Export a file that can be consumed by the software defined in software_compatibility. Alternatively, exports a string representation of the file (in case the invenotry should be downloaded from a browser, for example)

Parameters:¶

vehicle_specs
filename: str | None = None¶
export_format: str = 'file'¶: file, string, bw2io
directory : str or pathlib.Path¶: str. path to export the file to.
ecoinvent_version : str¶: str. “3.5”, “3.6”, “3.7” or “3.8”

If “string”, returns a string.

Returns:¶: returns the file path of the exported inventory.
Return type:¶: str

write_lci(ecoinvent_version: str, year: int) → list[dict]¶

Return the inventory as a dictionary If there are several values for one exchange, uncertainty information is generated. If presamples is True, returns the inventory as well as a presamples matrix. If presamples is False, returns the inventory with characterized uncertainty information.

Returns:¶: a dictionary that contains all the exchanges
Return type:¶: dict

carculator_utils.export.load_inventories() → list[dict]¶: Load LCIs to fetch metadata from.

carculator_utils.export.load_mapping(filename) → dict[tuple[str, str, str, str], tuple[str, str, str, str]]¶: Load mapping dictionary between two versions of ecoinvent.

carculator_utils.export.rename_mapping(filename: str) → dict[str, str]¶: Load the file rename_powertrains.yaml and return a dictionary

API¶

Truck Input Parameter¶

Array¶

Driving cycle¶

Energy consumption¶

Truck Model¶

Noise Model¶

Hot pollutants emissions¶

Inventory calculation¶

Inventory export¶

Background systems¶