25 create demo input files installer for easy access to resources folder

docs/index.md

@@ -10,6 +10,8 @@ To learn about the models, go to the [Overview](./T3CO_Overview.md)
 
 To get started with the tool, go to the [Installation Guide](./installation.md)
 
+To run your first analysis after installing T3CO, go to the [Quick Start Guide](./quick_start.md)
+
 ## Usage
 **T3CO** is a general framework allowing a user to determine the total cost of ownership (TCO) of a FASTSim vehicle (paired with a FASTSim DriveCycle(s) for determining fuel efficiency). The user can also determine performance of gradability, acceleration, and range. In addition to straight TCO computation there is also the option to optimize a vehicle powertrain such that it meets performance optional targets while also optionally minimizing TCO.
 

docs/installation.md

@@ -27,8 +27,10 @@ T3CO depends on [Python](https://www.python.org/downloads/)>=3.8 and <=3.10. To
     t3co\Scripts\activate
     ```
 
-## Installing From [PyPI](https://pypi.org/project/t3co/)
-T3CO can be easily installed from PyPI. This is the preferred method when using T3CO as a dependency for a project. To install the latest release:
+## Installing T3CO Python Package
+T3CO is available on PyPI and as a public access GitHub repository. This gives the user two ways of installing the T3CO Python Package.
+### 1. Installing From [PyPI](https://pypi.org/project/t3co/) <a name=install-from-pypi></a>
+T3CO can be easily installed from PyPI. This is the preferred method when using T3CO to run analysis using input files. To install the latest release:
 ```bash
 pip install t3co
 ```
@@ -38,15 +40,15 @@ To install a specific version (for example T3CO v1.0.8):
 pip install t3co==1.0.8
 ```
 
-## From GitHub
+### 2. From [GitHub](https://github.com/NREL/T3CO)
 T3CO can also be installed directly from the GitHub repository for accessing demo input files and running T3CO using the Command Line Interface.
 
-First, clone the repository from [GitHub](https://github.com/NREL/T3CO):
+First, [clone](https://git-scm.com/docs/git-clone) the repository from [GitHub](https://github.com/NREL/T3CO):
 ```bash
 git clone https://github.com/NREL/T3CO.git T3CO
 ```
 
-From within the [Python environment](#setting-up-env) Navigate to the parent directory containing the T3CO repository e.g. `cd github/T3CO/` and run:
+From within the [Python environment](#setting-up-env) Navigate to the parent directory containing the T3CO repository e.g. `cd GitHub/T3CO/` and run:
 ```bash
 pip install -e .
 ```
@@ -67,5 +69,21 @@ If there are updates or new releases to T3CO that don't show in the local versio
 git pull origin main
 ```
 
+
+## Copying T3CO Demo Input Files <a name=copy-demo-inputs></a>
+The `t3co.resources` folder contains all the necessary input files needed for running T3CO. However, it sometimes is difficult to navigate to these files when installing. To help with this, run this command on the Command Line Interface.
+
+```bash
+install_t3co_demo_inputs
+```
+
+The user will receive these questions on the command line:
+
+`Do you want to copy the T3CO demo input files? (y/n):`
+
+`Enter the path where you want to copy demo input files:`
+
+Choose `y` and provide the desired destination path to get a `demo_inputs` folder containing the `t3co.resources` files copied to your local directory.
+
 ## Running your first analysis
 To learn about the tool and run your first T3CO analysis, proceed to the [Quick Start Guide](./quick_start.md)

docs/quick_start.md

@@ -21,7 +21,18 @@ Note that `scenario.selection` and `vehicle.selection` are expected by the tool
 The auxiliary input files in the [`t3co/resources/auxiliary/`](https://github.com/NREL/T3CO/tree/4aed80f4a2caf65abfc7be176fcf34107621e1fe/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](https://github.com/NREL/T3CO/blob/4aed80f4a2caf65abfc7be176fcf34107621e1fe/t3co/resources/T3COConfig.csv) file, run these commands from the parent directory:
+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 most effective way to run the sweep module is to call a specific "Analysis" from the ***Config*** file using the `config.analysis_id` key.
+
+### Running Sweep Module from PyPI-installed T3CO
+The easiest way to run the `t3co.sweep` module is to use a local copy of the demo input files. If the [`install_t3co_demo_inputs`](./installation.md#copy-demo-inputs) command is used to copy `demo_inputs` to your local directory after [installing from PyPI](./installation.md#install-from-pypi), run the `t3co.sweep` module from any directory. 
+
+```bash
+python -m t3co.sweep --analysis-id=0 --config=<path/to/demo_inputs/T3COConfig.csv>
+```
+Point `--config` to the `T3COConfig.csv` file path and `--analysis-id` to the desired `config.analysis_id` (either an existing one or a newly added "Analysis" in the `demo_inputs/T3COConfig.csv` file. Default = `0`).
+
+### Running Sweep Module from a Cloned Github repo
+For running `config.analysis_id`=0 (or a user desired "Analysis") from the [Demo Config](https://github.com/NREL/T3CO/blob/4aed80f4a2caf65abfc7be176fcf34107621e1fe/t3co/resources/T3COConfig.csv) file on a cloned GitHub repo, run these commands from the parent directory:
 
 ```bash
 cd t3co
@@ -98,4 +109,6 @@ optional arguments:
 ```
 
 ## 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***](t3co_outputs_descriptions.md) 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.
+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***](t3co_outputs_descriptions.md) 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.

pyproject.toml

@@ -44,4 +44,5 @@ Repository = "https://github.com/NREL/T3CO"
 "Bug Tracker" = "https://github.com/NREL/T3CO/issues"
 
 [project.scripts]
-t3co-cli = "t3co:sweep"
+install_t3co_demo_inputs = "t3co.utilities.demo_inputs_installer:main"
+

t3co/resources/T3COConfig.csv

@@ -1,4 +1,4 @@
 analysis_id,analysis_name,vehicle_file,scenario_file,dst_dir,resfile_suffix,write_tsv,selections,drive_cycle,vehicle_life_yr,TCO_method,ess_max_charging_power_kw,fs_fueling_rate_kg_per_min,fs_fueling_rate_gasoline_gpm,fs_fueling_rate_diesel_gpm,algorithms,lw_imp_curves,eng_eff_imp_curves,aero_drag_imp_curves,lw_imp_curve_sel,eng_eff_imp_curve_sel,aero_drag_imp_curve_sel,skip_all_opt,constraint_range,constraint_accel,constraint_grade,objective_tco,constraint_c_rate,constraint_trace_miss_dist_percent_on,objective_phev_minimize_fuel_use,activate_tco_payload_cap_cost_multiplier,activate_tco_fueling_dwell_time_cost,fdt_frac_full_charge_bounds,activate_mr_downtime_cost
-0,Demo-NoOpt,resources/inputs/demo/Demo_FY22_vehicle_model_assumptions.csv,resources/inputs/demo/Demo_FY22_scenario_assumptions.csv,../tco_results/t3co_results,,FALSE,"[12,13,14,20]",,4,DIRECT,100,7.2,10,15,NSGA2,resources/auxiliary/LightweightImprovementCostCurve.csv,resources/auxiliary/EngineEffImprovementCostCurve.csv,resources/auxiliary/AeroDragImprovementCostCurve.csv,MDHD_noprogram_2020,MDHD_large_noprogram_2020,SleeperTractorHighRoof_noprogram_2021,TRUE,FALSE,TRUE,TRUE,TRUE,FALSE,FALSE,FALSE,TRUE,TRUE,"[0.1,0.9]",TRUE
-1,Demo-Opt,resources/inputs/demo/Demo_FY22_vehicle_model_assumptions.csv,resources/inputs/demo/Demo_FY22_scenario_assumptions.csv,../tco_results/t3co_results,,FALSE,[1],,4,EFFICIENCY,100,7.2,10,15,NSGA2,resources/auxiliary/LightweightImprovementCostCurve.csv,resources/auxiliary/EngineEffImprovementCostCurve.csv,resources/auxiliary/AeroDragImprovementCostCurve.csv,MDHD_noprogram_2020,MDHD_large_noprogram_2020,SleeperTractorHighRoof_noprogram_2021,FALSE,FALSE,TRUE,TRUE,TRUE,FALSE,FALSE,FALSE,TRUE,TRUE,"[0.1,0.9]",TRUE
-2,Demo-Scenario,resources/inputs/demo/Demo_FY22_vehicle_model_assumptions.csv,resources/inputs/demo/Demo_FY22_scenario_assumptions.csv,../tco_results/t3co_results,,FALSE,[12],long_haul_cyc.csv,4,EFFICIENCY,100,7.2,10,15,NSGA2,resources/auxiliary/LightweightImprovementCostCurve.csv,resources/auxiliary/EngineEffImprovementCostCurve.csv,resources/auxiliary/AeroDragImprovementCostCurve.csv,MDHD_noprogram_2020,MDHD_large_noprogram_2020,SleeperTractorHighRoof_noprogram_2021,TRUE,FALSE,TRUE,TRUE,TRUE,FALSE,FALSE,FALSE,TRUE,TRUE,"[0.1,0.9]",TRUE
+0,Demo-NoOpt,./inputs/demo/Demo_FY22_vehicle_model_assumptions.csv,./inputs/demo/Demo_FY22_scenario_assumptions.csv,../tco_results/t3co_results,,FALSE,"[12,13,14,20]",,4,DIRECT,100,7.2,10,15,NSGA2,./auxiliary/LightweightImprovementCostCurve.csv,./auxiliary/EngineEffImprovementCostCurve.csv,./auxiliary/AeroDragImprovementCostCurve.csv,MDHD_noprogram_2020,MDHD_large_noprogram_2020,SleeperTractorHighRoof_noprogram_2021,TRUE,FALSE,TRUE,TRUE,TRUE,FALSE,FALSE,FALSE,TRUE,TRUE,"[0.1,0.9]",TRUE
+1,Demo-Opt,./inputs/demo/Demo_FY22_vehicle_model_assumptions.csv,./inputs/demo/Demo_FY22_scenario_assumptions.csv,../tco_results/t3co_results,,FALSE,[1],,4,EFFICIENCY,100,7.2,10,15,NSGA2,./auxiliary/LightweightImprovementCostCurve.csv,./auxiliary/EngineEffImprovementCostCurve.csv,./auxiliary/AeroDragImprovementCostCurve.csv,MDHD_noprogram_2020,MDHD_large_noprogram_2020,SleeperTractorHighRoof_noprogram_2021,FALSE,FALSE,TRUE,TRUE,TRUE,FALSE,FALSE,FALSE,TRUE,TRUE,"[0.1,0.9]",TRUE
+2,Demo-Scenario,./inputs/demo/Demo_FY22_vehicle_model_assumptions.csv,./inputs/demo/Demo_FY22_scenario_assumptions.csv,../tco_results/t3co_results,,FALSE,[12],long_haul_cyc.csv,4,EFFICIENCY,100,7.2,10,15,NSGA2,./auxiliary/LightweightImprovementCostCurve.csv,./auxiliary/EngineEffImprovementCostCurve.csv,./auxiliary/AeroDragImprovementCostCurve.csv,MDHD_noprogram_2020,MDHD_large_noprogram_2020,SleeperTractorHighRoof_noprogram_2021,TRUE,FALSE,TRUE,TRUE,TRUE,FALSE,FALSE,FALSE,TRUE,TRUE,"[0.1,0.9]",TRUE

t3co/sweep.py

@@ -1328,7 +1328,7 @@ def skip_scenario(sel: int, scenario_name: str, verbose: bool = False) -> bool:
     )
 
     args = parser.parse_args()
-    print(f"gl.SWEEP_PATH: {gl.SWEEP_PATH}")
+    print(f"Sweep file path: {gl.SWEEP_PATH}")
 
     # selections can be an int, or list of ints, or range expression
     if args.config is None:
@@ -1349,17 +1349,17 @@ def skip_scenario(sel: int, scenario_name: str, verbose: bool = False) -> bool:
     else:
         try:
             config = rs.Config()
-            config.from_file(filename=args.config, analysis_id=args.analysis_id)
+            config.from_file(filename=Path(args.config), analysis_id=args.analysis_id)
         except ValueError:
             print(f"Config analysis_id not valid: {args.analysis_id}")
             config = rs.Config()
-            config.validate_analysis_id(filename=args.config)
+            config.validate_analysis_id(filename=Path(args.config))
         selections = config.selections
-        vehicles = gl.SWEEP_PATH.parents[0] / config.vehicle_file
-        scenarios = gl.SWEEP_PATH.parents[0] / config.scenario_file
-        eng_eff_imp_curves = gl.SWEEP_PATH.parents[0] / config.eng_eff_imp_curves
-        lw_imp_curves = gl.SWEEP_PATH.parents[0] / config.lw_imp_curves
-        aero_drag_imp_curves = gl.SWEEP_PATH.parents[0] / config.aero_drag_imp_curves
+        vehicles = Path(args.config).parent / config.vehicle_file
+        scenarios = Path(args.config).parent / config.scenario_file
+        eng_eff_imp_curves = Path(args.config).parent / config.eng_eff_imp_curves
+        lw_imp_curves = Path(args.config).parent / config.lw_imp_curves
+        aero_drag_imp_curves = Path(args.config).parent / config.aero_drag_imp_curves
         write_tsv = config.write_tsv
 
     look_for = args.look_for

t3co/utilities/demo_inputs_installer.py

@@ -0,0 +1,34 @@
+import shutil
+import os
+from pathlib import Path
+
+def main():
+    """
+    This function requests user inputs for whether and where to copy T3CO demo input files from the t3co.resources folder. It then calls the copy_demo_input_files function.
+    """
+    choice = input("Do you want to copy the T3CO demo input files? (y/n): ").strip().lower()
+    if choice == "y":
+        destination_path = input("Enter the path where you want to copy demo input files: ").strip()
+        copy_demo_input_files(destination_path)
+    else:
+        print("Demo input files were not copied.")
+
+def copy_demo_input_files(destination_path:str):
+    """
+    This function copies the t3co.resources folder that includes demo input files to a user input destination_path.
+
+    Args:
+        destination_path (str | Path): Path of destination directory for copying t3co.resources folder
+    """
+    source_path = Path(__file__).parents[1] / 'resources'
+    destination_path = Path(destination_path)/'demo_inputs'
+
+    if not destination_path.exists():
+        os.makedirs(destination_path)
+
+    for item in source_path.iterdir():
+        if item.is_file():
+            shutil.copy(item, destination_path / item.name)
+        else:
+            shutil.copytree(item, destination_path / item.name)
+    print(f"T3CO demo input files copied to {destination_path.resolve()}")