diff --git a/.gitignore b/.gitignore index 51225fb..38a1cf5 100644 --- a/.gitignore +++ b/.gitignore @@ -6,6 +6,7 @@ *.docx *.pdf *.svg +!docs/t3co_logo.svg *.csv !t3co/resources/inputs/**/*.csv !t3co/**/*.csv diff --git a/docs/config_inputs_descriptions.md b/docs/config_inputs_descriptions.md index 4a0e5d5..8f75a29 100644 --- a/docs/config_inputs_descriptions.md +++ b/docs/config_inputs_descriptions.md @@ -1,7 +1,7 @@ # Config Input Parameters Descriptions -| Config Input Parameters | Descriptions | Data Formats Accepted | +| **Config Input Parameter** | **Description** | **Data Type(s) Accepted** | |------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------| | analysis_id | Index for managing T3CO analyses or runs | int | | analysis_name | Name of T3CO Analysis for user's reference | string | @@ -9,7 +9,7 @@ | scenario_file | Filepath to scenario file relative to /t3co/ folder | string | | dst_dir | Filepath to results destination directory | string | | write_tsv | Boolean switch to save intermediate results files | bool | -| selections | List of selections from vehicle/scenario files to include in the analysis. Takes input as an integer or list of integers. '-1' makes T3CO run all vehicles in the vehicle file | int/list | +| selections | List of selections from vehicle/scenario files to include in the analysis. Takes input as an integer or list of integers. '-1' makes T3CO run all vehicles in the vehicle file | int/list\[int\] | | vehicle_life_yr | Override number of TCO years for all selections.. If left blank, T3CO uses selection specific vehicle_life_yr from scenario file | int | | ess_max_charging_power_kw | Override ESS max charging power for all selections. If left blank, T3CO uses selection specific ess_max_charging_power_kw from scenario file | float | | fs_fueling_rate_kg_per_min | Override gaseous fueling fill rate for all selections. If left blank, T3CO uses selection specific fs_fueling_rate_kg_per_min from scenario file | float | diff --git a/docs/scenario_inputs_descriptions.md b/docs/scenario_inputs_descriptions.md index a507439..384b54a 100644 --- a/docs/scenario_inputs_descriptions.md +++ b/docs/scenario_inputs_descriptions.md @@ -1,13 +1,13 @@ # Scenario Input Parameters Descriptions -| Input Parameter Names | Description | Data Type(s) Accepted | +| **Scenario Input Parameter** | **Description** | **Data Type(s) Accepted** | |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------| | selection | Selection number that is used to match with the corresponding vehicles on the Demo_FY22_vehicle_assumptions.csv file | int | | scenario_name | Name of the vehicle and scenario - Includes names | string | | veh_year | Current year | int | | drive_cycle | Relative filepath of drivecycle input file(s) from /t3co/resources/cycles/ folder - accepts single drivecyle path, composite cycles (for example: '[("EPA_Ph2_rural_interstate_65mph.csv", .86), ("EPA_Ph2_urban_highway_55mph.csv", .09), ("EPA_Ph2_transient.csv", .05)]'), or path to folder containing multiple drivecycles (results in corresponding number of scenarios) | string | | vmt_reduct_per_yr | not used | | -| vmt | Vehicle Miles Traveled as an array/list with length>=vehicle_life_yr | list | +| vmt | Vehicle Miles Traveled as an array/list with length>=vehicle_life_yr | list\[int\] | | constant_trip_distance_mi | not used | | | vehicle_life_yr | Number of years to calculate TCO for - generally the expected life of the vehicle in years | int | | desired_ess_replacements | not used | | @@ -38,7 +38,7 @@ fc_ice_base_cost_dol | Cost of Fuel Convertor | gvwr_kg | Gross Vehicle Weight Rating upper limit in kg for the vehicle's weight class | float | | gvwr_credit_kg | Additional allowable weight in kg for advanced vehicles (eg. 2000lb credit for Class 8 BEVs) | float | | fuel_type | Fuel name - should be one of : ['diesel', 'gasoline', 'hydrogen', 'electricity', 'cng']. For hybrids, use the primary fuel | string | -| maint_oper_cost_dol_per_mi | Vehicle maintenance operating cost in dollars per mile traveled as vector of length equal to number of TCO years | list | +| maint_oper_cost_dol_per_mi | Vehicle maintenance operating cost in dollars per mile traveled as vector of length equal to number of TCO years | list\[float\] | | vocation | Vocation of the vehicle - only for user reference | string | | model_year | Vehicle model year | int | | region | Region name is used as a key to find the right fuel prices for the analysis. Refer to /t3co/resources/FuelPrices.csv for region name | string | @@ -64,7 +64,7 @@ fc_ice_base_cost_dol | Cost of Fuel Convertor | constraint_grade | Optimization constraint - Gradeability 1.25% grade and 6% grade | bool | | objective_tco | Boolean switch for minimizing TCO as optimization objective | bool | | constraint_c_rate | Optimization constraint - Charge Rate | bool | -| shifts_per_year | Number of shifts/drivecycle instances per year traveled by the vehicle as a vector of length equal to number of TCO years. if = 0, then it's calculated from vmt and daily distance | list | +| shifts_per_year | Number of shifts/drivecycle instances per year traveled by the vehicle as a vector of length equal to number of TCO years. if = 0, then it's calculated from vmt and daily distance | list\[int\] | | motor_power_override_kw_fc_demand_on_pct | For PHEV, percentage motor power override as fraction | float | | soc_norm_init_for_accel_pct | Initial normalized SOC for acceleration test (only PHEV) | float | | soc_norm_init_for_grade_pct | Initial normalized SOC for gradeability test (only PHEV) | float | @@ -77,10 +77,10 @@ fc_ice_base_cost_dol | Cost of Fuel Convertor | fdt_dwpt_fraction_power_pct | Fraction of vehicle power consumption through dynamic wireless power transfer | float | | fdt_available_freetime_hr | Number of hours of dwell time that do not incur opportunity cost penalty (eg., charging vehicle during scheduled lunch stops) | float | | fdt_avg_overhead_hr_per_dwell_hr | Number of hours of overhead time during fueling/charging (eg., detour to gas station, time taken for plugging in charger, etc.) | float | -| fdt_frac_full_charge_bounds | Lower and Upper bounds for fractional charge as a list [, ]. is lowest fraction of charge/tank for a fractional charge at a fueling stop. is the highest fraction of charge/tank capacity above which it is preferred to rather fill up the batter/tank | list | +| fdt_frac_full_charge_bounds | Lower and Upper bounds for fractional charge as a list [, ]. is lowest fraction of charge/tank for a fractional charge at a fueling stop. is the highest fraction of charge/tank capacity above which it is preferred to rather fill up the batter/tank | list\[float\] | | activate_mr_downtime_cost | Boolean switch to activate maintenance and repair (M&R) downtime opportunity cost calculation | bool | | mr_planned_downtime_hr_per_yr | Regular/planned maintenance time in hours per year | float | -| mr_unplanned_downtime_hr_per_mi | Unplanned maintenance time per mile traveled as a vector with length equal to number of TCO years | list | +| mr_unplanned_downtime_hr_per_mi | Unplanned maintenance time per mile traveled as a vector with length equal to number of TCO years | list\[float\] | | mr_tire_replace_downtime_hr_per_event | Downtime hours per tire replacement event | float | | mr_avg_tire_life_mi | Average life of tire in miles after which a tire replacement event takes place | float | -| insurance_rates_pct_per_yr | Insurance rates as a percent of MSRP per year as vector with length equal to number of TCO years | list | +| insurance_rates_pct_per_yr | Insurance rates as a percent of MSRP per year as vector with length equal to number of TCO years | list\[float\] | diff --git a/docs/t3co_logo.svg b/docs/t3co_logo.svg new file mode 100644 index 0000000..c8c2abd --- /dev/null +++ b/docs/t3co_logo.svg @@ -0,0 +1,112 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/t3co_output_parameter_descriptions.md b/docs/t3co_output_parameter_descriptions.md new file mode 100644 index 0000000..fad80b6 --- /dev/null +++ b/docs/t3co_output_parameter_descriptions.md @@ -0,0 +1,68 @@ +# T3CO Output Parameters Descriptions + +| **T3CO Output Parameter** | **Description** | **Data type(s)** | +| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | +| selection | Selection number of vehicle/scenario | int | +| scenario_name | Name of the selected scenario/vehicle | string | +| veh_year | Current year | int | +| veh_pt_type | Vehicle powertrain type | string | +| pareto_front_number | Optimization solution number from pareto front | int | +| run_time_[s] | T3CO run time for selected vehicle/scenario | float | +| algorithm | Algorithm for pymoo optimization. From  ["NSGA2", "PatternSearch"] | string | +| n_gen | Number of generations of genetic algorithm optimization | int | +| fvals_over_gens | Optimization objective space values across generations | float | +| design_cyc_trace_miss_dist_frac | Fractional difference between achieved cumulative distance and prescribed cumulative distance. If composite drivecycle is input, the distance trace miss is output as a list | dict/list[dict] | +| design_cyc_trace_miss_time_frac | Fractional difference between achieved time when trace miss is and prescribed cumulative distance. If composite drivecycle is input, the time trace miss is output as a list | dict/list[dict] | +| design_cyc_trace_miss_speed_mps | Maximum speed (mps) by which vehicle’s speed falls behind prescribed speed trace. If composite drivecycle is input, the time trace miss is output as a list | dict/list[dict] | +| design_cycle_EA_err | Fractional difference between achieved energy consumption vs consumption estimated based on the input drivecycle. Checks for conservation of energy in the simulated results. | dict/list[dict] | +| accel_EA_err | Fractional difference between achieved energy consumption vs consumption estimated based on the acceleration test drivecycle with current vehicle mass.  Checks for conservation of energy in the simulated results | dict/list[dict] | +| accel_loaded_EA_err | Fractional difference between achieved energy consumption vs consumption estimated based on the acceleration test drivecycle with fully laden vehicle. Checks for conservation of energy in the simulated results | dict/list[dict] | +| grade_6_EA_err | Fractional difference between achieved energy consumption vs consumption estimated based on the 6 % gradeability test drivecycle with fully laden vehicle.  Checks for conservation of energy in the simulated results | dict/list[dict] | +| grade_125_EA_err | Fractional difference between achieved energy consumption vs consumption estimated based on the 1.25 % gradeability test drivecycle with fully laden vehicle.  Checks for conservation of energy in the simulated results | dict/list[dict] | +| final_cda_pct | Optimization result for percent improvement in Cd\*A (drag coefficient times frontal area) - based on aero drag improvement curve | float | +| final_eng_eff_pct | Optimization result for percent improvement in engine efficiency - based on engine efficiency improvement curve | float | +| final_ltwt_pct | Optimization result for percent improvement in vehicle mass - based on lightweighting improvement curve | float | +| final_max_motor_kw | Optimization result for motor power in kW - bound between scenario.knob_min_motor_kw and scenario.knob_max_motor_kw | float | +| final_battery_kwh | Optimization result for ESS max capacity in kWh - bound between scenario.knob_min_ess_kwh and scenario.knob_max_ess_kwh | float | +| final_max_fc_kw | Optimization result for fuel converter max power in kW - bound between scenario.knob_min_fc_kw and scenario.knob_max_fc_kw | float | +| final_fs_kwh | Optimization result for fuel storage max capacity in kWh - bound between scenario.knob_min_fs_kwh and scenario.knob_max_fs_kwh | float | +| RangeMiAch | Range achieved by vehicle based on drivecycle simulation | float | +| target_TargetRangeMi | Target range constraint for design vehicle during optimization | float | +| delta_TargetRangeMi | Difference between range achieved from simulation and target range of the design vehicle | float | +| minSpeed6PercentGradeIn5minAch | Final speed achieved by design vehicle during 6 % gradeability test run for 5 mins | float | +| target_minSpeed6PercentGradeIn5min | Target speed for design vehicle during 6 % gradeability test run for 5 mins | float | +| delta_6PercentGrade | Difference between final speed achieved and target speed during 6% gradeability test | float | +| minSpeed1point25PercentGradeIn5minAch | Final speed achieved by design vehicle during 1.25 % gradeability test run for 5 mins | float | +| target_minSpeed1point25PercentGradeIn5min | Target speed for design vehicle during 1.25 % gradeability test run for 5 mins | float | +| delta_1point25PercentGrade | Difference between final speed achieved and target speed during 1.25% gradeability test | float | +| max0to60secAtGVWRAch | Time taken achieved by fully laden design vehicle during acceleration for 0 to 60mph | float | +| target_max0to60secAtGVWR | Target time taken for fully laden design vehicle during acceleration for 0 to 60mph | float | +| delta_0to60sec | Difference between time taken by simulated vehicle and target time for fully laden acceleration test from 0 to 60mph | float | +| max0to30secAtGVWRAch | Time taken achieved by fully laden design vehicle during acceleration for 0 to 30mph | float | +| target_max0to30secAtGVWR | Target time taken for fully laden design vehicle during acceleration for 0 to 30mph | float | +| delta_0to30sec | Difference between time taken by simulated vehicle and target time for fully laden acceleration test from 0 to 30mph | float | +| glider_cost_Dol | Estimated glider component cost in dollars - contributes to MSRP | float | +| fuel_converter_cost_Dol | Estimated fuel converter component cost in dollars - contributes to MSRP | float | +| fuel_storage_cost_Dol | Estimated fuel storage component cost in dollars - contributes to MSRP | float | +| motor_pwr_electrics_cost_Dol | Estimated motor and power electronics component cost in dollars - contributes to MSRP | float | +| plug_cost_Dol | Estimated plugin charger component cost in dollars - contributes to MSRP | float | +| battery_cost_Dol | Estimated battery/ESS component cost in dollars - contributes to MSRP | float | +| purchase_tax_Dol | Estimated purchased/excise tax  in dollars - calculated from MSRP | float | +| msrp_total_Dol | Estimated manufacturer's suggested retail price in dollars - calculated from vehicle component costs | float | +| total_fuel_cost_Dol | Estimated fuel operating cost in dollars - calculated from energy consumption and fuel prices | float | +| total_maintenance_cost_Dol | Estimated maintenance operating cost in dollars - calculated from VMT and scenario.maint_oper_cost_dol_per_mi | float | +| mpgge | Miles per Gallon of Gasoline Equivalent - from drivecycle simulation | float | +| grid_mpgge | Miles per Gallon of Gasoline Equivalent effect to grid - mpgge times charger efficiency | float | +| mpgde | Miles per Gallon of Diesel Equivalent - from drivecycle simulation | float | +| kwh_per_mi | Energy spent per mile of operation - estimated from drivecycle simulation | float | +| payload_cap_cost_multiplier | Lost payload capacity opportunity cost factor - represents the fractionally extra vehicle required to compensate for reduced payload capacity compared to conventional vehicle - Currently only for Class 8 vehicles | float | +| fueling_dwell_time_hr | Net dwell time of vehicle due to fueling/charging - used to estimate downtime opportunity cost | float | +| MR_downtime_hr | Net dwell time of vehicle due to maintenance & repair (planned, unplanned, and tire replacement) - used to estimate downtime opportunity cost | float | +| total_downtime_hr | Total downtime due to fueling/charging and maintenance events | float | +| dwell_time_cost_Dol | Estimated labor cost incurred during fueling dwell time | float | +| MR_downtime_cost_Dol | Estimated labor cost incurred during maintenance & repair downtime | float | +| downtime_cost_Dol | Estimated maintenance and repair downtime opportunity cost in dollars - estimation is based on config.TCO_method | float | +| payload_capacity_cost_Dol | Lost payload capacity opportunity cost in dollars - estimated from payload_cap_cost_multiplier and estimated tco | float | +| insurance_cost_Dol | Estimated insurance cost of vehicle in dollars - estimated from MSRP and scenario.insurance_rates_pct_per_yr | float | +| residual_cost_Dol | Estimated residual cost of vehicle in dollars (residual value is the negative of residual cost) | float | +| discounted_tco_Dol | Estimated discounted Total Cost of Ownership in dollars - Calculated using one of DIRECT or EFFICIENCY method from different cost components, discounted year over year at a rate of scenario.discount_rate_pct_per_yr, and calculated for scenario.vehicle_life_yr | float | \ No newline at end of file diff --git a/docs/vehicle_inputs_descriptions.md b/docs/vehicle_inputs_descriptions.md index 6c22913..7a5eff9 100644 --- a/docs/vehicle_inputs_descriptions.md +++ b/docs/vehicle_inputs_descriptions.md @@ -1,6 +1,6 @@ # Vehicle Input Descriptions -| vehicle parameter | description | data type | +| **Input Parameter Name** | **Description** | **Data Type(s) Accepted** | |--------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------|----------------| | scenario_name | Vehicle name |  string | | selection | Vehicle database ID |  int | @@ -13,15 +13,15 @@ | drive_axle_weight_frac | Fraction of weight on the drive axle while stopped |  float | | wheel_base_m | Wheelbase, $m$ |  float | | cargo_kg | Cargo mass including passengers, $kg$ |  float | -| veh_override_kg | Total vehicle mass, overrides mass calculation, $kg$ |  Option | +| veh_override_kg | Total vehicle mass, overrides mass calculation, $kg$ (Optional) |  float | | comp_mass_multiplier | Component mass multiplier for vehicle mass calculation |  float | | fs_max_kw | Fuel storage max power output, $kW$ |  float | | fs_secs_to_peak_pwr | Fuel storage time to peak power, $s$ |  float | | fs_kwh | Fuel storage energy capacity, $kWh$ |  float | | fs_kwh_per_kg | Fuel specific energy, $\frac{kWh}{kg}$ |  float | | fc_max_kw | Fuel converter peak continuous power, $kW$ |  float | -| fc_pwr_out_perc | Fuel converter output power percentage map, x values of fc_eff_map |  Array1 | -| fc_eff_map | Fuel converter efficiency map |  Array1 | +| fc_pwr_out_perc | Fuel converter output power percentage map, x values of fc_eff_map |  list\[float\] | +| fc_eff_map | Fuel converter efficiency map |  list\[float\] | | fc_eff_type | Fuel converter efficiency type, one of [SI, ATKINSON, DIESEL, H2FC, HD_DIESEL] Used for calculating fc_eff_map, and other calculations if H2FC |  string | | fc_sec_to_peak_pwr | Fuel converter time to peak power, $s$ |  float | | fc_base_kg | Fuel converter base mass, $kg$ |  float | @@ -29,8 +29,8 @@ | min_fc_time_on | Minimum time fuel converter must be on before shutoff (for HEV, PHEV) |  float | | idle_fc_kw | Fuel converter idle power, $kW$ |  float | | mc_max_kw | Peak continuous electric motor power, $kW$ |  float | -| mc_pwr_out_perc | Electric motor output power percentage map, x values of mc_eff_map |  Array1 | -| mc_eff_map | Electric motor efficiency map |  Array1 | +| mc_pwr_out_perc | Electric motor output power percentage map, x values of mc_eff_map |  list\[float\] | +| mc_eff_map | Electric motor efficiency map |  list\[float\] | | mc_sec_to_peak_pwr | Electric motor time to peak power, $s$ |  float | | mc_pe_kg_per_kw | Motor power electronics mass per power output, $\frac{kg}{kW}$ |  float | | mc_pe_base_kg | Motor power electronics base mass, $kg$ |  float | @@ -64,5 +64,5 @@ | trans_kg | Transmission mass, $kg$ |  float | | trans_eff | Transmission efficiency |  float | | ess_to_fuel_ok_error | Maximum acceptable ratio of change in ESS energy to expended fuel energy (used in hybrid SOC balancing), $\frac{\Delta E_{ESS}}{\Delta E_{fuel}}$ |  float | -| fc_peak_eff_override | Fuel converter efficiency peak override, scales entire curve |  Option | -| mc_peak_eff_override | Motor efficiency peak override, scales entire curve |  Option | +| fc_peak_eff_override | Fuel converter efficiency peak override, scales entire curve(Optional) |  float | +| mc_peak_eff_override | Motor efficiency peak override, scales entire curve (Optional) |  float | diff --git a/mkdocs.yml b/mkdocs.yml index f8399fb..b7dde1c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -21,7 +21,7 @@ markdown_extensions: theme: name: material - favicon: t3co_logo.png + favicon: t3co_logo.svg highlightjs: true hljs_languages: - python @@ -42,6 +42,8 @@ nav: - Vehicle: vehicle_inputs_descriptions.md - Scenario: scenario_inputs_descriptions.md - Config: config_inputs_descriptions.md + - Results: + - Outputs: t3co_output_parameter_descriptions.md - Code Reference: - CodeFlow: CodeFlow.md - T3CO Modules: diff --git a/t3co/sweep.py b/t3co/sweep.py index a79a9fd..f5209a9 100644 --- a/t3co/sweep.py +++ b/t3co/sweep.py @@ -63,7 +63,6 @@ "max0to30secAtGVWRAch": "", "target_max0to30secAtGVWR": "", "delta_0to30sec": "", - "discounted_tco": "", "glider_cost_Dol": "", "fuel_converter_cost_Dol": "", "fuel_storage_cost_Dol": "", @@ -74,6 +73,8 @@ "msrp_total_Dol": "", "total_fuel_cost_Dol": "", "total_maintenance_cost_Dol": "", + "discounted_tco_Dol": "", + }