Quick Start Guide to T3CO¶
A total cost analysis is only as good as its inputs. Generating T3CO results requires equal parts of investment in inputs gathering as it is in running the tool. To make things easier, we provide 500+ demo scenarios for the user to choose from to run T3CO.
Inputs¶
T3CO contains three main input files and several auxiliary files that are referenced in the main files for different purposes.
Vehicle, Scenario, and Config¶
The main input files are the Vehicle, Scenario, and Config. T3CO provides users with demo input files to get started. One or more Vehicle-Scenario pair selections are necessary to run T3CO:
- Vehicle contains sets of FASTSim vehicle input parameters that define the powertrain and vehicle dynamics of the selected Vehicle-Scenario pair. Each entry in the Vehicle file is called a "Vehicle Model" and is referenced using
vehicle.selectionas a key. [Demo Vehicles] - Scenario contains cost, infrastructure, and optimization related input parameters that define a certain scenario. Each entry in the Scenario file is called a "Scenario Model" and is referenced using
scenario.selectionas a key.scenario.selectionandvehicle.selectionare expected to match to be able to run a Vehicle-Scenario pair . [Demo Scenarios] - Config contains easy ways to manage T3CO model settings and to save the inputs needed to run a set of selections of Vehicle-Scenario pairs. It also contains paths to various input files and some Scenario parameter overrides to be used globally on all selections. Users can also specify a path to the output directory in which T3CO results need to be saved. Each entry in the Config file refers to an "Analysis" and is accessed using
config.analysis_id[Demo Analyses]
Auxiliary Inputs¶
The auxiliary input files in the t3co/resources/auxiliary/ folder include FuelPrices.csv, ResidualValues.csv, AeroDragImprovementCostCurve.csv, LightweightImprovementCostCurve.csv, and EngineEffImprovementCostCurve.csv. These files contain important cost and model assumptions that are necessary to run different aspects of the T3CO cost models. Users can select the default auxiliary input files and choose the relevant set of assumptions. They can also add new entries to these files, or create their own auxiliary input files and mention the new paths in the Config file.
Running T3CO¶
After checking the inputs and creating/modifying an "Analysis" on the Config file, the next step is to execute the models. The t3co/sweep.py module is the main script that needs to be run to perform a TCO analysis. And the easiest way to run the sweep module is to call a specific "Analysis" from the Config file using the config.analysis_id key. For running config.analysis_id=0 from the Demo Config file, run these commands from the parent directory:
Other Command Line Interface arguments¶
Use the command below to get a list of all CLI arguments:
$ python sweep.py --help
usage: SWEEP [-h] [--config CONFIG] [--analysis-id ANALYSIS_ID] [--vehicles VEHICLES] [--scenarios SCENARIOS] [--selections [SELECTIONS ...]] [--eng-curves ENG_CURVES] [--lw-curves LW_CURVES]
[--aero-curves AERO_CURVES] [--look-for LOOK_FOR] [--skip-all-opt] [--skip-input-validation] [--exclude [EXCLUDE ...]] [--algorithms [ALGORITHMS ...]] [--dst-dir DST_DIR]
[--dir-mark DIR_MARK] [--file-mark FILE_MARK] [--skip-save-veh] [--x-tol X_TOL] [--f-tol F_TOL] [--n-max-gen N_MAX_GEN] [--pop-size POP_SIZE] [--nth-gen NTH_GEN] [--n-last N_LAST]
[--range-overshoot-tol RANGE_OVERSHOOT_TOL] [---missed-trace-correction] [--max-time-dilation MAX_TIME_DILATION] [--min-time-dilation MIN_TIME_DILATION]
[--time-dilation-tol TIME_DILATION_TOL] [--write-tsv WRITE_TSV]
The sweep.py module is the main script to run T3CO
optional arguments:
-h, --help show this help message and exit
--config CONFIG Input Config file (default: ./resources/T3COConfig.csv)
--analysis-id ANALYSIS_ID
Analysis key from input Config file - 'config.analysis_id' (default: 0)
--vehicles VEHICLES Input file for Vehicle models (default: ./resources/inputs/demo/Demo_FY22_vehicle_model_assumptions.csv)
--scenarios SCENARIOS
Input file for Scenario models (default: ./resources/inputs/demo/Demo_FY22_scenario_assumptions.csv)
--selections [SELECTIONS ...]
Selections desired to run. Selections can be an int, or list of ints, or range expression. Ex: --selections 234 or --selections "[234,236,238]" or --selections "range(234,
150, 2)" (default: None)
--eng-curves ENG_CURVES
Input file for engine efficiency improvement cost curves (default: ./resources/auxiliary/EngineEffImprovementCostCurve.csv)
--lw-curves LW_CURVES
Input file for lightweighting improvement cost curves (default: ./resources/auxiliary/LightweightImprovementCostCurve.csv)
--aero-curves AERO_CURVES
Input file for aerodynamics improvement curves (default: ./resources/auxiliary/AeroDragImprovementCostCurve.csv)
--look-for LOOK_FOR A string for string matching, example --look_for 'FCEV' or -look_for '["FCEV", "HEV"]' (default: )
--skip-all-opt, --skopt
If --skip_all_opt used, all runs skip optimization (default: False)
--skip-input-validation, --skiv
If --skip_input_validation used, no pre-validation of inputs is run before sweep commences (default: True)
--exclude [EXCLUDE ...]
Overrides -look_for. a string for string matching to exclude runs, example -exclude 'FCEV' or -look_for '["FCEV", "HEV"]' (default: >{-<>-}<)
--algorithms [ALGORITHMS ...], --algos [ALGORITHMS ...], --algo [ALGORITHMS ...]
Enter algorithm or list of algorithms, or "ensemble" to use all, to use for optimization: ['NSGA2', 'NelderMead', 'PatternSearch', 'PSO'] ex: -algos PatternSearch | -algos
'["PatternSearch", "NSGA2"]' | -algos "ensemble" (default: NSGA2)
--dst-dir DST_DIR Directory to store T3CO results (default: ./results)
--dir-mark DIR_MARK Name for results directory in addition to timestamp (default: )
--file-mark FILE_MARK
Prefix to add to the result file names (default: )
--skip-save-veh Toggle result vehicle model YAML file saving off (default: False)
--x-tol X_TOL Parameter space tolerance for optimization (default: 0.001)
--f-tol F_TOL Objective space tolerance for optimzation (default: 0.001)
--n-max-gen N_MAX_GEN
Max number of optimizer iterations regardless of algorithm (default: 1000)
--pop-size POP_SIZE population of each generation (default: 25)
--nth-gen NTH_GEN Period of generations in which to evaluate if convergence happens during optimization (default: 1)
--n-last N_LAST Number of generations to look back for establishing convergence during optimization (default: 5)
--range-overshoot-tol RANGE_OVERSHOOT_TOL
Range overshoot tolerance, example '0.20' allows 20% range overshoot. Default of 'None' does not constrain overshoot. (default: None)
---missed-trace-correction
Activate FASTSim time-dilation to correct missed trace (default: False)
--max-time-dilation MAX_TIME_DILATION
Maximum time dilation factor to 'catch up' with trace (default: 10)
--min-time-dilation MIN_TIME_DILATION
Minimum time dilation to let trace 'catch up' (default: 0.1)
--time-dilation-tol TIME_DILATION_TOL
Convergence criteria for time dilation (default: 0.001)
--write-tsv WRITE_TSV
Boolean toggle to save intermediary .TSV cost results files (default: False)
T3CO Results¶
After running the analysis, T3CO stores the results .CSV file in the directory specified by config.dst_dir (or the CLI argument --dst-dir). The results file includes a comprehensive list of Cost Outputs that were calculated by the various T3CO Modules. In addition to the T3CO outputs, all the Vehicle input parameters (denoted by a prefix: input_vehicle_value_), Scenario input parameters(denoted by a prefix: scenario_), and Config parameters (denoted by a prefix: config_) are also present in the results file. When the optional optimization module is run, the optimized vehicle parameters are also listed ((denoted by a prefix: optimized_vehicle_value_)) instead of NaN values for non-optimization runs.