OMEGA Documentation
Revised: Mar 19, 2024
1. Model Overview
The OMEGA model has been developed by EPA to evaluate policies for reducing greenhouse gas (GHG) emissions from light duty vehicles. Like the prior releases, this latest version is intended primarily to be used as a tool to support regulatory development by providing estimates of the effects of policy alternatives under consideration. These effects include the costs associated with emissions-reducing technologies and the monetized effects normally included in a societal benefit-cost analysis, as well as physical effects that include emissions quantities, fuel consumption, and vehicle stock and usage. In developing this OMEGA version 2.0, our goal was to improve modularity, transparency, and flexibility so that stakeholders can more easily review the model, conduct independent analyses, and potentially adapt the model to meet their own needs.
1.1. What’s New in This Version
EPA created OMEGA version 1.0 to analyze new GHG standards for light-duty vehicles proposed in 2011. The ‘core’ model performed the function of identifying manufacturers’ cost-minimizing compliance pathways to meet a footprint-based fleet emissions standard specified by the user. A preprocessing step involved ranking the technology packages to be considered by the model based on cost-effectiveness. Postprocessing of outputs was performed separately using a spreadsheet tool, and later a scripted process which generated table summaries of modeled effects. An overview of OMEGA version 1.0 is shown on the left of Fig. 1.1.
In the period since the release of the initial version, there have been significant changes in the light duty vehicle market including technological advancements and the introduction of new mobility services. Advancements in battery electric vehicles (BEVs) with greater range, faster charging capability, and expanded model availability, as well as potential synergies between BEVs, ride-hailing services and autonomous driving are particularly relevant when considering pathways for greater levels of emissions reduction in the future. OMEGA version 2.0 has been developed with these trends in mind. The model’s interaction between consumer and producer decisions allows a user to represent consumer responses to these new vehicles and services. The model now also has been designed to have expanded capability to model a wider range of GHG program options, which is especially important for the assessment of policies that are designed to address future GHG reduction goals. In general, with the release of version 2.0, our goal is to improve usability and flexibility while retaining the primary functions of the original version of OMEGA. The right side of Fig. 1.1 shows the overall model flow for OMEGA version 2.0 and highlights the main areas that have been revised and updated.
Update #1: Expanded model boundaries. In defining the scope of this model version, we have attempted to simplify the process of conducting a run by incorporating into the model some of the pre- and post-processing steps that had previously been performed manually. At the same time, we recognize that an overly-expansive model boundary can result in requirements for inputs that are difficult to specify. To avoid this, we have set the input boundary only so large as to capture the elements of the system we assume are responsive to policy. This approach helps to ensure that model inputs such as technology costs and emissions rates can be quantified using data for observable, real-world characteristics and phenomena, and in that way enable transparency by allowing the user to maintain the connection to the underlying data. For the assumptions and algorithms within the model boundary, we aim for transparency through well-organized model code and complete documentation.
Update #2: Independent Policy Module. The previous version of OMEGA was designed to analyze a very specific GHG policy structure in which the vehicle attributes and regulatory classes used to determine emissions targets were incorporated into the code throughout the model. In order to make it easier to define and analyze other policy structures, the details regarding how GHG emissions targets are determined and how compliance credits are treated over time are now included in an independent Policy Module and associated policy inputs. This allows the user to incorporate new policy structures without requiring revisions to other code modules. Specifically, the producer decision module no longer contains any details specific to a GHG program structure, and instead functions only on very general program features such as fleet averaging of absolute GHG credits and required technology shares.
Update #3: Modeling of multi-year strategic producer decisions. As a policy analysis tool, OMEGA is intended to model the effect of policies that may extend well into the future, beyond the timeframe of individual product cycles. Year-by-year compliance decisions account for management of credits which can carry across years in the context of projections for technology cost and market conditions which change over time. The timeframe of a given analysis can be specified anywhere from near-term to long-term, with the length limited only by inputs and assumptions provided by the user.
Update #4: Addition of a consumer response component. The light-duty vehicle market has evolved significantly in the time since the initial release of OMEGA. In particular, as the range of available technologies and services has grown wider, so has the range of possible responses to policy alternatives. The model structure for this version includes a Consumer Module that can be used to project how the light-duty vehicle market would respond to policy-driven changes in new vehicle prices, fuel operating costs, and other consumer-facing elements. The Consumer Module outputs the estimated consumer responses, such as overall vehicle sales and sales shares, as well as vehicle re-registration and use, which together determine the stock of new and used vehicles and the associated allocation of total VMT.
Update #5: Addition of feedback loops for producer decisions. This version of OMEGA is structured around modeling the interactions between vehicle producers responding to a policy and consumers who own and use vehicles affected by the policy. These interactions are bi-directional, in that the producer’s compliance planning and vehicle design decisions will both influence, and be influenced by, the sales and shares of vehicles demanded and the GHG credits assigned under the policy. Iterative feedback loops have now been incorporated; between the Producer and Consumer modules to ensure that modeled vehicles would be accepted by the market at the quantities and prices offered by the producer, and between the Producer and Policy modules to account for the compliance implications of each successive vehicle design and production option considered by the producer.
Update #6: Use of absolute vehicle costs and emissions rates. The previous version of OMEGA modeled the producer application of technologies to a fleet of vehicles that was otherwise held fixed across policy alternatives. With the addition of a consumer response component that models market share shifts, this version utilizes absolute costs and emissions rates to compare vehicle design and purchase decisions across vehicle types and market classes.
1.2. Inputs and Outputs
Like other models, OMEGA relies on the user to specify appropriate inputs and assumptions. Some of these may be provided by direct empirical observations, for example the number of currently registered vehicles. Others might be generated by modeling tools outside of OMEGA, such as physics-based vehicle simulation results produced by EPA’s ALPHA model, or transportation demand forecasts from DOE’s NEMS model. OMEGA has adopted data elements and structures that are generic, wherever possible, so that inputs can be provided from whichever sources the user deems most appropriate.
The inputs and assumptions are categorized according to whether they define the policies under consideration, or define the context within which the analysis occurs.
Policy alternative inputs describe the standards themselves, including the program elements and methodologies for determining compliance as would be defined for an EPA rule in the Federal Register and Code of Federal Regulations.
Analysis context inputs and assumptions cover the range of factors that the user assumes are independent of the policy alternatives. The context inputs may include fuel costs, costs and emissions rates for a particular vehicle technology package, attributes of the existing vehicle stock, consumer demand parameters, existing GHG credit balances, producer decision parameters, and many more. The user may project changes in the context inputs over the analysis timeframe based on other sources, but for a given analysis year the context definition requires that these inputs are common across the policy alternatives being compared.
A list of the input files with links to full descriptions can be found in Chapter 5.
The primary outputs are producer compliance status, vehicles produced, and the costs and physical effects for a set of policy alternatives within a given analysis context. These outputs are expressed in absolute values, so that incremental effects, costs, and benefits can be evaluated by comparing two policy alternatives for a given analysis context. For example, comparing a No Action scenario to an Action (or Policy) Alternative. Those same policy alternatives can also be compared using other analysis context inputs to evaluate the sensitivity of results to uncertainty in particular assumptions. For example, comparing the incremental effects of a new policy in high fuel price and low fuel price analysis contexts.
1.3. Model Structure and Key Modules
OMEGA has been set up so that primary components of the model are clearly delineated in such a way that changing one component of the model will not require code changes throughout the model. The four main modules — Producer, Consumer, Policy, and Effects — are each defined along the lines of their real-world analogs. Producers and consumers are represented as distinct decision-making agents, which each exist apart from the regulations defined in the Policy Module. Similarly, the effects, both environmental and societal, exist apart from producer and consumer decision-making agents and the policy. This structure allows a user to analyze policy alternatives with consistently defined producer and consumer behavior. It also provides users the option of interchanging any of OMEGA’s default modules with their own, while preserving the consistency and functionality of the larger model.
Producer Module: This module projects the decisions of the regulated entities (producers) in response to policy alternatives, while accounting for consumer demand. The regulated entities can be specified as individual companies, or considered in aggregate as a collection of companies, depending on the assumptions made by the user regarding how GHG credits are averaged or transferred between entities.
Consumer Module: This module projects demand for vehicle sales, ownership and use in response to changes in vehicle characteristics such as price, ownership cost, and other key attributes.
Policy Module: This module determines the compliance status for a producer’s possible fleet of new vehicles based on the characteristics of those vehicles and the policy defined by the user. Policies may be defined as performance-based standards using fleet averaging (for example, determining compliance status by the accounting of fungible GHG credits), as a fixed requirement without averaging (for example, a minimum required share of BEVs), or as a combination of performance-based standards and fixed requirements.
Effects Module: This module projects the physical and cost effects that result from the modeling of producers, consumers, and policy within a given analysis context. Examples of physical effects include the stock and use of registered vehicles, electricity and gasoline consumption, and the GHG and criteria pollutant emissions from tailpipe and upstream sources. Examples of cost effects include vehicle production costs, ownership and operation costs, societal costs associated with GHG and criteria pollutants, and other societal costs associated with vehicle use.
1.4. Iteration and Convergence
OMEGA is intended to find a solution which simultaneously satisfies producer, consumer, and policy requirements while minimizing the producer generalized costs. OMEGA’s Producer and Consumer modules represent distinct decision-making entities, with behaviors defined separately by the user. Without some type of interaction between these modules, the model would likely not arrive at an equilibrium of vehicles supplied and demanded. For example, a compliance solution which only minimizes producer generalized costs without consideration of consumer demand may not satisfy the market requirements at the fleet mix and level of sales preferred by the consumer. Similarly, the interaction between Producer and Policy modules ensures that with each subsequent iteration, the compliance status for the new vehicle fleet under consideration is correctly accounted for by the producer. Since there is no general analytical solution to this problem of alignment between producers, consumers, and policy which also allows model users to independently define producer and consumer behavior and the policy alternatives, OMEGA uses an iterative search approach.
1.5. Analysis Resolution
The policy response projections generated by OMEGA are centered around the modeled production, ownership, and use of light-duty vehicles. It would not be computationally feasible (nor would it be necessary) to distinguish between the nearly 20 million light-duty vehicles produced for sale each year in the US, and hundreds of millions of vehicles registered for use at any given time. Therefore, OMEGA is designed to operate using ‘vehicles’ which are actually aggregate representations of individual vehicles, while still retaining sufficient detail for modeling producer and consumer decisions, and the policy response. The resolution of vehicles can be set for a given analysis, and will depend on the user’s consideration of factors such as the availability of detailed inputs, the requirements of the analysis, and the priority of reducing model run time.
2. Getting Started
The OMEGA model is written in the open source Python programming language. The model is available in two different packages to suit the particular requirements of the end user:
For users intending to run the OMEGA model with input modifications only, an executable version is available along with a directory structure and a complete set of sample inputs. This Getting Started chapter is focused on this executable version.
For users intending to run the OMEGA model with user-definable submodules or other code modifications, a developer version is available in a GitHub repository. For more information on the developer version, please refer to the Developer Guide.
2.1. Downloading OMEGA
Releases of the OMEGA model executables are be available at:
2.2. Running OMEGA
Opening the executable will bring up the OMEGA graphical user interface. The executable takes a few moments to start up, (or it may take longer, depending on the speed of the user’s computer), as it contains compressed data which must be extracted to a temporary folder. A self-contained Python installation is included in the executable and Python does not need to be installed by the user in order to run OMEGA. A console window will also be displayed in addition to the GUI window which shows additional runtime information and any diagnostic messages that may be generated.
The GUI has two file system selection boxes in the Run Model
tab; one for choosing the batch file (e.g. test_batch.csv
) and one for choosing the folder where the batch will execute and produce outputs. The output folder for the batch will contain the model source code, the batch file, a log file, a requirements file describing the Python installation details, and subfolders for each simulation session. These session folders will contain an in
and an out
folder. The in
folder contains the complete set of inputs to the session, and the out
folder contains the simulation outputs and log file.
2.3. Step by Step Example Model Run
Please refer to the GUI Basics documentation for a step by step execution of an example model run.
2.4. Viewing the Results
After OMEGA model runs have completed, the results generated for each session are available in the associated out
folder in .csv
and .png
file formats.
3. Running OMEGA using the Graphical User Interface (GUI)
3.1. GUI Basics
The EPA OMEGA Model is highly modular and can be run using several methods including but not limited to the command line, the Python environment, and the Graphical User Interface (GUI). The GUI is the best option for new users of OMEGA to reproduce existing model runs and become familiar with the model’s input and output structure. This introduction will guide the user through running by example.
After launching the GUI, the Intro
tab will appear as shown in Fig. 3.1.
Selecting the Run Model
tab allows the user to set up an OMEGA model run. The elements of the Run Model
tab are shown in Fig. 3.2.
Description of the Run Model
tab elements:
Note: Context help is always available by hovering the cursor over an element.
- Element 1 - Tab Selection
Tabs to select areas of the GUI.
- Element 2 - Input Batch File
Allows the user to select the Input Batch File. The Input Batch File is a standard OMEGA input file that describes the complete parameters for a model run. The Input Batch File may be selected from the file menu or the “…” button within the element field. When the Input Batch File is selected, the complete path will be displayed. Hovering the cursor over the complete path will display just the base file name.
- Element 3 - Output Batch Directory
Allows the user to select the Output Batch Directory. The Output Batch Directory instructs OMEGA where to store the results of a model run. The Output Batch Directory may be selected from the file menu or the folder button within the element field. When the Output Batch Directory is selected, the complete path be displayed. Hovering the cursor over the complete path will display just the base file name.
- Element 4 - Project Description
Allows the user to enter any useful text that will be saved in an optional Configuration File for future reference. This element is free format text to allow standard functions (such as copy and paste) to be used. The saved text will be displayed whenever the Configuration File is opened.
- Element 5 - Event Monitor
The Event Monitor prompts the user during model run setup (file selection, etc.) and keeps a running record of OMEGA model execution in real time. This is a standard text field to allow simple copying of text as needed for further study or debugging purposes. Log files are also produced in the batch and session output folders as the model runs, in fact the Event Monitor echoes these files as the model runs.
- Element 6 - Run Model
When everything is properly configured, this button will be enabled for initiation of the OMEGA model run.
3.2. Running OMEGA
The elements required to run the model are loaded by creating a new model run, or by using an existing Configuration File.
Note: The Event Monitor will provide additional guidance through the model loading process.
3.2.1. Creating a New Model Run
Select the
Run Model
tab.Load an existing OMEGA Input Batch File using the file menu or button within the field. (Required)
Select a new or existing OMEGA Output Batch Directory using the file menu or button within the field. (Required)
Add a Project Description. (Optional)
Use the file menu to save the new Configuration File. (Optional)
The Run Model
tab will look similar to Fig. 3.3 below.
3.2.2. Existing Configuration File
If a model run configuration was previously saved, the configuration may be reloaded to simplify repeating runs. From the file menu, select Open Configuration File
to launch a standard File Explorer window to load an existing Configuration File. When properly loaded, the Run Model
tab will look similar to Fig. 3.3 below.
3.2.3. Running the Model
With all of the model requirements loaded, select the Run Model
tab and the ‘Model Run’ button will be enabled. Press the Model Run
button to start the model run.
As the model is running, the Run Model
tab will look similar to Fig. 3.4 below.
The GUI provides real time information during the model run:
The model starting information is detailed in the event monitor. This includes the time and Input Batch File used.
The model status, error count, and elapsed time from model start are continuously updated adjacent to the
Run Model
button.The load on the system CPU and system Memory is monitored in the Windows Status Bar at the bottom of the GUI window.
The Event Monitor provides a continuous stream of information gathered from the simultaneous OMEGA processes.
When the model run is completed, the Run Model
tab will look similar to Fig. 3.5 below.
Final GUI Data:
The model ending information is detailed in the event monitor. This includes the time and the Output Batch Directory used.
The model status and final model run time are displayed adjacent to the
Run Model
button.
3.3. Interpreting the Model Results
Each session folder has an out
folder which contains a number of default outputs. The outputs fall into three categories described in this section: image file outputs, detailed outputs in csv-formatted text files, and a run log text file.
3.3.1. Auto-generated image file outputs
While the detailed modeling results are primarily recorded in csv-formatted text files (described in Table 3.2), OMEGA also produces a number of standard graphical image outputs. This lets the user quickly and easily review the results, without requiring any further post-processing analyses. Some of the various types of auto-generated images are listed in Table 3.1.
Abbreviated File Name |
File Description |
---|---|
…Cert Mg v Year…png |
compliance including credit transfers, initial and final compliance state |
…Shares.png |
absolute market share by market category, market class, regulatory class and context size class |
…V Cert CO2e gpmi…png |
sales-weighted average vehicle certification CO2e g/mi by market category / class |
…V Tgt CO2e gpmi…png |
sales-weighted average vehicle target CO2e g/mi by market category / class |
…V kWh pmi…png |
sales-weighted average vehicle cert direct kWh/mi by market category / class |
…V GenCost…png |
sales-weighted average vehicle producer generalized cost by market category / class |
…V Mg…png |
sales-weighted average vehicle cert CO2e Mg by market category / class |
Example: Reading a manufacturer compliance plot
The manufacturer compliance plot provides several visual details on how the manufacturers are achieving compliance (or not) for each model year, and is a good starting point to inform the user of the model results. An example is shown in Fig. 3.6.
The following describes the key features of this plot:
The Y-axis represents the total CO2e emissions, in metric tons (or Mg) for each model year.
The blue line and dots represent the required industry standard for each year, in metric tons (Mg).
The orange line represents the industry-achieved net standard after credits have been applied or carried to other model years. The orange dots represent the existence of credits banked prior to the analysis start year (they are placed on the chart to be visible, but the Mg level of the dots has no meaning.)
Green arrows indicate the source model year (arrow origin) and the model year in which credits have been applied (arrow end.)
Vertical down arrows, in red, indicate that some or all of the credits generated by that model year expired unused.
Red circle-x symbols indicate years that compliance was not achieved, after considering the carry-forward and carry-back of credits.
Example: Using image files to compare policy alternative results
In this example, the action alternative (Alt 1) is generally more stringent than the no-action alternative (Alt 0), so we should expect to see this difference in policy reflected in the results. Fig. 3.7 highlights some of the main differences between these two alternatives. The upper panels show the GHG targets (grams CO2e per mile), which decrease in each model year through 2030 in Alt 0, while in Alt 1 the targets are decreasing through 2050 with an accelerated rate after 2041. While the GHG targets are determined at the vehicle level, the plots shown here are weighted average values for each market class. The underlying individual vehicle targets are available in the ‘…vehicles.csv’ output file (see Table 3.2) and are a function of the respective policy definitions and the attributes of the vehicles that are used in the assignment of targets. See Section 4.2 and Table 4.4 for more detail on the policy definitions. For both policy alternatives, the targets are lower for vehicles in the non-hauling market category compared to hauling. Note that there is no difference in the targets between BEV and ICE vehicles within the hauling and non-hauling market categories.
The lower panels show the certification emissions, which like the targets, are also expressed here in CO2e grams per mile. These values are the result of producer, consumer, and policy elements in the model run. For the less stringent Alt 0, the ICE market classes show some modest reduction in certification emissions in the earlier years, which then level off and begin increasing after 2035. For BEVs, certification levels actually begin with negative values due to the policy application of off-cycle credits; specifically, ‘AC leakage’ technology, as defined in an ‘offcycle_credits.csv’ input file. In Alt 0, upstream emissions are applied to BEV certification values beginning in 2035. The no-action policy upstream emissions rates (defined in a ‘policy_fuels.csv’ file) decline from 2035 to 2040, as reflected in the declining BEV certification emissions over that timeframe. For the more stringent Alt 1, ICE certification values decrease nearly through 2050. In 2045, the available ICE technologies have been exhausted, and certification values level off at the minimum possible levels. BEV certification levels remain constant throughout for Alt 1, and reflect only off-cycle credits since there is no accounting for upstream emissions in this policy alternative.
Fig. 3.8 shows the compliance results for the two policy alternatives used in this example. The year-to-year changes in targets (blue points) reflect the CO2e grams per mile targets shown in Fig. 3.7, as well as changes in sales and other policy elements used to calculate and scale the absolute Mg CO2e values, such as multipliers and VMT. Certification emissions (red points) generally overlay the targets in each year. Similarly, compliance emissions (orange line) are aligned with certification emissions, since the strategic use of hisorical (pre-analysis) credits has not been implemented in the model for this example. Minor corrections for year-over-year credit transfers are shown with the green arrows, although the magnitude of transfers is small in this case; larger transfers would be discernible as a difference between the red points and orange line. For Alt 1, the certification emissions begin to depart from the targets in 2045. With insufficient credits to carry-forward (or carry-back) to 2045 and 2046, those two years are non-compliant (red circle-x symbols.) The remaining years, 2047-2050, have an indeterminate compliance status since the model was only run out to 2050, and there is still a possible opportunity to carry-back credits from future years.
Fig. 3.9 shows new vehicle shares by market class. The more stringent Alt 1 has higher BEV shares for both hauling and non-hauling market classes compared to the less stringent Alt 0. The significant increase in BEV shares in 2048 coincides with the producer’s state of non-compliance; the producer’s attempts to maximize BEV share at this time is limited by the consumer share response (defined in a ‘sales_share_params.csv’), and the specified limits on producer price cross-subsidization (defined in the batch .csv
file.) BEV shares also increase in the less stringent Alt 0, although at a slower rate than the action alternative. This increase occurs smoothly as BEVs become relatively less expensive due to cost learning over time. A step-up and plateau in BEV shares from 2040 to 2044 is due to the no-action policy’s minimum production requirement values, specified in a ‘required_sales_share.csv’ file.
Fig. 3.10 shows the vehicle production costs (upper panels) and producer generalized costs (lower panels) for the two policy alternatives. BEV production costs decrease at a faster rate than ICE vehicles due to cost learning. Still, in the less stringent no-action policy (Alt 0) BEV production costs remain higher than ICE costs throughout the analysis timeframe. That’s not true for the more stringent action alternative (Alt 1), where production cost parity is reached in 2045 as additional technology added causes ICE costs to converge with BEV costs. The lower panels of Fig. 3.10 show that producer generalized costs follow the same trends as vehicle production costs. However, there are a few important differences; First, the generalized costs in this example include the portion of fuel cost that producers assume is valued by consumers in the purchase decision (defined in ‘producer_generalized_cost.csv’), making generalized costs higher than production costs. Note that the increase in Alt 0 ICE production costs in 2035 actually corresponds to a decrease in generalized costs, as the addition of ICE technology changes the fuel consumption rates, and therefore the fuel operating costs per mile. Second, because of the difference in fuel operating costs for BEV and ICE vehicles, cost parity occurs earlier for generalized costs than for production costs.
In this example, overall new vehicle sales are determined by the assumed price elasticity of demand (as defined in the batch .csv
file), and the change in generalized cost for vehicles relative to the analysis context. Fig. 3.11 shows the sales results for the two policy alternatives. Because the no-action alternative (left panel) is the same as the context policy, the model automatically calibrates the aggregate generalized cost in each year so that overall sales volumes match the analysis context sales projections. See Section 4.4 for more details. The right panel shows sales for the action alternative, Alt 1. Deviations from the projected sales, above and below, are the result of differences in generalized costs between the two alternatives. Prior to 2035, Alt 1 has lower generalized costs then Alt 0, so sales are higher than the context projections. After 2035, Alt 1 has higher generalized costs, so sales are lower than the context projections. Fig. 3.13 shows the incremental generalized costs as derived from the ‘…summary_results.csv’ output file.
3.3.2. Detailed csv-formatted text output files
While the auto-generated image files are convenient for quickly looking at high-level results, the csv-formatted output files provide a full accounting of detailed results. This includes analysis vehicle information as well as credit logs to provide a better understanding of producer compliance decisions, and intermediate iteration steps to help illuminate the producer-consumer modeling. The resolution of the majority of these output files is at the same level defined by the user in the run inputs; namely by producer, vehicle, and analysis year. Table 3.2 summarizes the complete set of csv-formatted output files.
Abbreviated File Name |
File Description |
---|---|
…GHG_credit_balances.csv |
beginning and ending model year GHG credit balances by calendar year |
…GHG_credit_transactions.csv |
model year GHG credit transactions by calendar year |
…inputfile_metadata.csv |
data related to the complete set of input files |
…manufacturer_annual_data.csv |
manufacturer compliance and cost data by model year |
…new_vehicle_prices.csv |
new vehicle sales-weighted average manufacturer generalized cost data by model year |
…powertrain_cost_results.csv |
vehicle-level technology tracking data by model year and age |
…producer_consumer_iteration_log.csv |
detailed producer-consumer cross-subsidy iteration data by model year |
…summary_results.csv |
contains summarized data by year and is the source of the data for most of the image files |
…vehicle_annual_data.csv |
registered count and VMT data by model year and age |
…vehicles.csv |
detailed base year and compliance (produced) vehicle data |
Two of these output files, in particular, may be helpful for the user to better understand the details of the model results; ‘summary_results.csv’ and ‘powertrain_cost_results.csv.’ The examples given here are meant to illustrate how these outputs can be used to quantify specific effects of the policies.
Summary results output file
The top level ‘…summary_results.csv’ output file is unique among the csv-formatted output files in that it combines results for all sessions in a batch into a single file. While some of the other output files contain significantly more detail and vehicle-level resolution, the summary file is a convenient source for some of the important key outputs, and is aggregated to a single row for each session + analysis year.
Example: Using a ‘summary_results.csv’ file to compare policy alternative results
Fig. 3.12 shows vehicle production costs for the action (Alt 1) and no-action (Alt 0) policy alternatives. These values are the same as those shown in the auto-generated images in Fig. 3.10, combined into a single plot. In the right panel, the incremental costs have been calculated from the ‘summary_results.csv’ file. The most impactful effects of the policy definitions can be seen here: in 2035, the incremental cost of Alt 1 is reduced as upstream emissions accounting is introduced in the no-action case; in 2042, the incremental cost begins to increase as the Alt 1 year-over-year stringency increases.
Fig. 3.13 shows the producer generalized costs for the action and no-action policy alternatives. As with the auto-generated image files showing generalized costs, the costs here are higher than vehicle production costs because of the example’s inclusion of 5 years of fuel operating costs. The incremental generalized costs shown in the right panel are helpful for understanding the sales effects shown in Figure Fig. 3.11. In the years when the action alternative has higher generalized costs, new vehicles sales decrease relative to the analysis context projections; and when costs are lower, new vehicle sales are higher.
Vehicles output file
Example: Using the ‘vehicles.csv’ output file to compare policy alternatives
Fig. 3.14 shows the shares of applied technologies at the level of resolution specified by the tech package details in the ‘simulated_vehicles.csv’ input file. While the particular details of the technology package definitions are not relevant for the purpose of this example, the differences between policy alternatives is illustrative. With the more stringent action alternative (Alt 1), BEV shares are clearly higher than in Alt 0, especially in the years approaching 2050. The technology packages with ‘turb12’ and ‘atk2’ have lower certification emissions than the packages with ‘turb11’ and ‘gdi-only’, so the transition to the more advanced packages occurs earlier in the analysis timeframe under the more stringent Alt 1, accordingly.
3.3.3. Run log output file
Abbreviated File Name |
File Description |
---|---|
o2log…txt |
session console output |
The session log file contains console output and may provide useful information in the event of a runtime error.
Post-processing Notes
Post-compliance-modeling image files and other outputs are generated by omega_model.postproc_session
.
The producer-consumer iteration log and new vehicle price files as well as the log file are generated and/or saved during compliance modeling rather than post-processing.
Attention
A two-pass session will have results similar to the above example, but on a per-manufacturer basis with a commensurately larger number of outputs.
Attention
Running OMEGA from the GUI executable is by far the slowest way to run the model since it runs single-threaded. For large or complex runs, it’s recommended to run from the source code to take advantage of multiprocessing. See Chapter 6 for more details.
4. Model Architecture and Algorithms
OMEGA is structured around four main modules which represent the distinct and interrelated decision-making agents and system elements that are most important for modeling how policy influences the environmental and other effects of the light duty sector. This chapter begins with a description of the simulation process, including the overall flow of an OMEGA run, and fundamental data structures and model inputs. That section is followed by descriptions of the algorithms and internal logic of the Policy Module, Producer Module, and Consumer Module, and then by a section on the approach for Iteration and Convergence Algorithms between these three modules. Finally, the accounting method is described for the physical and monetary effects in the Effects Module.
Throughout this chapter, references to an example analysis are included to provide additional specificity to the explanations in the main text. These examples are highlighted in shaded boxes. Please refer to Section 3.2.3 for more information on how to run the model to recreate an existing analysis or generate a new one.
4.1. Overall Simulation Process
4.1.1. Simulation Scope and Resolution
The model boundary of OMEGA as illustrated in Fig. 4.1 defines the system elements which are modeled internally, and the elements which are specified as user inputs and assumptions. The timeframe of a given analysis spans the years between analysis start and end years defined by the user. Together, the boundary and analysis timeframe define the scope of an analysis.
Example: Analysis timeframe
For this example, the base year is defined as calendar year 2019. The year immediately following the base year is automatically used as the analysis start year. The analysis final year in this example is set to 2050 in the input batch file. Therefore, the analysis timeframe is a 31-year span, inclusive of 2020 and 2050. The selection of 2019 as the base year is automatically derived from the last year of historical data contained in the ‘vehicles.csv’ and ‘ghg_credits.csv’ input files. These inputs describe the key attributes and counts for registered vehicles, and producers’ banked Mg CO2e credits as they actually existed. Note that for this example, base year vehicle inputs are limited to MY2019 new vehicles and their attributes. For an analysis which is intended to project the impacts of various policy alternatives on the reregistration and use of earlier model years, the base year inputs would describe the entire stock of registered vehicles, including MY2018, MY2017, etc.
Typically, the analysis start year will already be in the past at the time the model is run. Having the most up-to-date base year data can reduce the number of historical years that need to be modeled, although as noted in the sidebar, there are usually limits to data availability. Some overlap between the modeled and historical years may be beneficial, as it gives the user an opportunity to validate key model outputs against actual data and adjust modeling assumptions if needed.
Model inputs for the policy alternatives and analysis context projections must be available for every year throughout the analysis timeframe. Many of the input files for OMEGA, utilize a ‘start_year’ field, which allows the user to skip years with repetitive inputs if desired. In general, OMEGA will carry over input assumptions from the most recent prior value whenever the user has not specified a unique value for the given analysis year. Similarly, in cases where the user-provided input projections do not extend to the analysis end year, the value in the last specified year is assumed to hold constant in subsequent years. In this example analysis, 2045 is the last year for which input values are specified in ‘cost_factors-criteria.csv’, so OMEGA will apply the same 2045 values for 2046 through 2050.
An OMEGA analysis can be conducted at various levels of resolution depending on the user’s choice of inputs and run settings. The key modeling elements where resolution is an important consideration include vehicles, technologies, market classes, producers, and consumers.
Vehicle resolution: The definition of a ‘vehicle’ in an OMEGA analysis is an important user decision that determines one of the fundamental units of analysis around which the model operates. In reality, the vehicle stock is made up of hundreds of millions of vehicles, owned and operated by a similarly large number of individuals and companies. Theoretically, a user could define the vehicle resolution down to the individual options and features applied, or even VIN-level of detail. But given limitations in computational resources, the OMEGA user will more likely define vehicles at the class or nameplate level (e.g. ‘crossover utility vehicle’, or ‘AMC Gremlin’.) Regardless of how vehicles are represented, OMEGA will retain the details of each vehicle throughout the model (including in the outputs) at the level of resolution that the user has chosen. For example, if a user defines vehicle inputs at the nameplate level, the outputs will report nameplate level vehicle counts, key attributes, emissions rates, and physical and cost effects.
Technology package resolution: In OMEGA, producer decisions are made using complete packages of technologies which are integral to, and inseparable from, the definition of a candidate vehicle. In other words, a change to any of the individual technology components would result in a different candidate vehicle. The ‘simulated_vehicles.csv’ file contains the information for each candidate vehicle that is needed for modeling producer decisions, including the costs and emissions rates that are associated with the technology package.
Technology component resolution: Though the model operates using full technology packages (mentioned above), it may sometimes be helpful to track the application of particular sub-components of a package. The user can choose to add flags to the ‘simulated_vehicles.csv’ file to identify which types of components are present on the candidate vehicles. These flags are then used by the model to tabulate the penetration of components in the vehicle stock over time.
Market class resolution: The level of detail, and type of information used within the Producer and Consumer modules is different. For example, we assume that consumers are not aware of the compliance implications and detailed design choices made by the producer, unless those factors are evident in the price, availability, or key attributes of a vehicle. Therefore, consumer decisions regarding the demanded shares of vehicles are modeled based on vehicle characteristics aggregated at the market class level. The user’s determination of the appropriate resolution for the market classes will depend on the chosen specification for share response modeling within the Consumer Module. Note that within the Consumer Module, while share response is modeled at the market class level, other consumer decisions (like reregistration and use) can be based on more detailed vehicle-level information.
Producer resolution: The producers in OMEGA are the regulated entities subject to the policy alternatives being analyzed and are responsible (together with the consumers and policy) for the decisions about the quantities and characteristics of the vehicles produced. The user can choose to model the producers either as an aggregate entity with the assumption that compliance credits are available in an unrestricted market (i.e. ‘perfect trading’), or as individual entities with a level of potential trading between firms that is specified by the user (i.e. between ‘no trading’ and ‘perfect trading’, the level of ‘imperfect trading’ that is considered by the model).
Consumer resolution: The approach to account for heterogeneity in consumers is an important consideration when modeling the interaction between producer decisions and the demand for vehicles. By taking advantage of user-definable submodules, a developer can set-up the Consumer Module to account for different responses between consumer segments.
Whatever the level of resolution, the detail provided in the inputs 1) must meet the requirements of the various modeling subtasks, and 2) will determine the level of detail of the outputs. When preparing analysis inputs, it is therefore necessary to consider the appropriate resolution for each module. For example:
Within the Policy Module, vehicle details are needed to calculate the target and achieved compliance emissions. This might include information about regulatory classification and any vehicle attributes that are used to define a GHG standard.
Within the Producer Module, the modeling of producer decisions requires sufficient detail to choose between compliance options based the GHG credits and generalized producer cost associated with each option.
Within the Consumer Module, the modeling of consumer decisions requires sufficient detail to distinguish between market classes for representing both the purchase choices among different classes, and the reregistration and use of vehicles within a given class.
Example: Modeling resolution
Modeling element |
Where is the resolution defined? |
Description of resolution in the example |
---|---|---|
Vehicle resolution |
vehicles.csv |
51 2019 base year vehicles differentiated by context size class (‘Small Crossover’ ‘Large Pickup’ etc) manufacturer_id and electrification_class (‘N’ ‘HEV’ ‘EV’) |
Technology package resolution: |
simulated_vehicles.csv |
578088 candidate vehicles for the analysis timeframe 2020 through 2050 with technology packages for ICE and BEV powertrains |
Technology component resolution: |
simulated_vehicles.csv |
detailed flags for identifying technology package contents of ac_leakage ac_efficiency high_eff_alternator start_stop hev phev bev weight_reduction deac_pd deac_fc cegr atk2 gdi turb12 turb11 |
Market class resolution |
consumer.market_classes.py user-definable submodule and market_classes.csv |
4 classes in 2 nested levels with BEV and ICE categories within first tier hauling and non-hauling categories |
Consumer resolution |
consumer.sales_share_gcam.py user-definable submodule |
consumer heterogeneity is inherent in share weights used to estimate market class shares |
Producer resolution |
input batch file and manufacturers.csv |
2 producers (‘OEM_A’ and ‘OEM_B’) and ‘Consolidate Manufacturers’ run setting set to FALSE |
4.1.2. Process Flow Summary
In an OMEGA session, the model runs by looping over analysis years and producers. Within each successive loop, the simulation of producer and consumer decisions results in new vehicles entering the stock of registered vehicles, and the reregistration and use of existing vehicles from the prior year’s stock.
As shown in Fig. 4.2 , this simulation process involves two iterative loops. In one loop, the Policy Module determines whether or not the producer’s strategic compliance target is met by the candidate production options under consideration. In the other iterative loop, the Consumer Module determines whether or not the market will accept the quantities of vehicles offered at the prices set by the producer. Both the Producer-Policy and the Producer-Consumer iterative loops must achieve convergence for the simulation to proceed. Once all the analysis years and producers have been completed, the effects calculations are performed and results are written to the output files.
4.1.3. Model Inputs
As described in the Section 1.2 overview, OMEGA model inputs are grouped into two categories; policy alternative inputs and analysis context inputs. The policy alternatives define the GHG standards that are being evaluated by the model run, while the analysis context refers collectively to the external assumptions that apply to all policies under analysis.
Policy Alternatives Inputs
An OMEGA run requires a full description of the GHG standards themselves so that the modeled producer compliance considerations are consistent with how an EPA rule would be defined in the Federal Register and Code of Federal Regulations. As described in Section 4.2, OMEGA is intended primarily for the analysis of fleet averaging standards, and the example provided here has been set up to illustrate how accounting rules for GHG credits in a fleet averaging program can be defined. This includes the coefficients for calculating emissions rate targets (gram CO2e per mile) based on vehicle attributes, the methods for determining emissions rate certification values (e.g. drive cycle and fuel definitions, off-cycle credits), and the rules for calculating and accounting for Mg CO2e credits over time (e.g. banking and trading rules, and lifetime VMT assumptions.) See Table 4.4 for a complete list of the policy alternative inputs used in this example.
Analysis Context Inputs
The analysis context defines the inputs and assumptions that the user assumes are independent of the policy alternatives. This clear delineation of exogenous factors is what enables the apples-to-apples comparison of policy alternatives within a given analysis context. This is the primary purpose for which OMEGA was designed – to quantify the incremental effects of a policy for informing policy decisions. At the same time, considering how the incremental effects of a policy might vary depending on the analysis context assumptions is a useful approach for understanding the sensitivity of the projected results to differences in assumptions.
Example: Analysis Context inputs for ‘Context A’
This example includes two policy alternatives (‘alt0’ and ‘alt1’) and two sets of analysis context assumptions (‘A’ and ‘B’.) Table 4.2 shows the complete set of input files and settings for Context A that would be defined in an input batch file for Context A.
Analysis context element |
Input file name/ Input setting value |
Description |
---|---|---|
Context Name |
AEO2021 |
Together with ‘Context Case’ setting, selects which set of input values to use from the fuel price and new vehicle market files. |
Context Case |
Reference case |
Together with ‘Context Name’ setting, selects which set of input values to use from the fuel price and new vehicle market files. |
Context Fuel Prices File |
context_fuel_prices.csv |
Retail and pre-tax price projections for any fuels considered in the analysis (e.g. gasoline, electricity.) |
Context New Vehicle Market File |
context_new_vehicle_market.csv |
Projections for new vehicle key attributes, sales, and mix under the analysis context conditions, including whatever policies are assumed. |
GHG Credits File |
ghg_credits.csv |
Balance of existing banked credits, by model year earned. |
Manufacturers File |
manufacturers.csv |
List of producers considered as distinct entities for GHG compliance. When ‘Consolidate Manufacturers’ is set to TRUE, in the batch input file, ‘consolidated_OEM’ value is used for all producers. |
Market Classes File |
market_classes.csv |
Market class ID’s for distinguishing vehicle classes in the Consumer Module. |
New Vehicle Price Elasticity of Demand |
-1 |
Scalar value of the price elasticity of demand for overall new vehicle sales. |
Onroad Fuels File |
onroad_fuels.csv |
Parameters inherent to fuels and independent of policy or technology (e.g. carbon intensity.) |
Onroad Vehicle Calculations File |
onroad_vehicle_calculations.csv |
Multiplicative factors to convert from certification energy and emissions rates to onroad values. |
Onroad VMT File |
annual_vmt_fixed_by_age.csv |
Annual mileage accumulation assumptions for estimating vehicle use in Consumer and Effects modules |
Producer Cross Subsidy Multiplier Max |
1.05 |
Upper limit price multiplier value considered by producers to increase vehicle prices though cross subsidies. |
Producer Cross Subsidy Multiplier Min |
0.95 |
Lower limit price multiplier value considered by producers to decrease vehicle prices though cross subsidies. |
Producer Generalized Cost File |
producer_generalized_cost.csv |
Parameter values for the producers generalized costs for compliance decisions (e.g. the producers view of consumers consideration of fuel costs in purchase decisions.) |
Production Constraints File |
production_constraints-cntxt_a.csv |
Upper limits on market class shares due to constraints on production capacity. |
Sales Share File |
sales_share_params-cntxt_a.csv |
Parameter values required to specify the demand share estimation in the Consumer Module. |
Vehicle Price Modifications File |
vehicle_price_modifications-cntxt_a.csv |
Purchase incentives or taxes/fees which are external to the producer pricing decisions. |
Vehicle Reregistration File |
reregistration_fixed_by_age.csv |
Proportion of vehicles reregistered at each age, by market class. |
Vehicle Simulation Results and Costs File |
simulated_vehicles.csv |
Vehicle production costs and emissions rates by technology package and cost curve class. |
Vehicles File |
vehicles.csv |
The base year vehicle information. |
Context Implicit Price Deflators File |
implicit_price_deflators.csv |
Factors for converting costs to a common dollar basis. |
Example: Unique Analysis Context inputs for ‘Context B’
While most of the example input files are common for contexts ‘A’ and ‘B’, in cases where context assumptions vary, input files are differentiated using ‘context_a’ and ‘context_b’ in the file names. Table 4.3 shows the input files and settings that are unique for Context B that would be defined in an input batch file.
Analysis context element |
Input file name/ Input setting value |
Difference between contexts ‘A’ and ‘B’ |
---|---|---|
Context Case |
High oil price |
Taken from AEO2021, Context A uses the Reference Case fuel prices and Context B uses the ‘High oil price’ case fuel prices. |
Producer Cross Subsidy Multiplier Max |
1.4 |
Context B uses a higher upper limit price multiplier value compared to the 1.05 value for Context A. |
Producer Cross Subsidy Multiplier Min |
0.6 |
Context B uses a reduced lower limit price multiplier value compared to the 0.95 value for Context A. |
Production Constraints File |
production_constraints-cntxt_b.csv |
Context B has a linearly increasing maximum production constraint for BEVs from 2020 to 2030, compared to Context A which has no production limits specified in that timeframe. |
Sales Share File |
sales_share_params-cntxt_b.csv |
Context B has BEV share weight parameters for the Consumer Module which represent a logistic function that increases earlier, reaching a value of 0.5 in 2025 instead of 2030 in Context A. In other words, Context B represents greater consumer demand for BEVs, all else equal. |
Vehicle Price Modifications File |
vehicle_price_modifications-cntxt_b.csv |
Context B introduces an external BEV purchase incentive of $10,000 in 2025, which decreases to $5,000 in 2027, and then linearly to zero in 2036 compared to Context A which has no purchase incentives in this timeframe. |
4.1.4. Projections and the Analysis Context
The output of an OMEGA run is a modeled projection of the future. While this projection should not be interpreted as a single point prediction of what will happen, it does represent a forecast that is the result of the modeling algorithms, inputs, and assumptions used for the run. Normally, these modeled projections of the future will vary from year-to-year over the analysis timeframe due to year-to-year changes in the policy, as well changes in producer decisions due to considerations of compliance strategy, credit utilization, and production constraints. Another reason that results in future are not constant from one year to the next is because the exogenous factors in the analysis context are themselves projections of the future, and any year-to-year changes in those factors will influence the model results.
It is important that we consider the relationship between these exogenous projections and the factors being modeled internally within OMEGA to avoid inconsistencies. Three situations are described here, along with an explanation for how the model integrates external projections in a consistent manner.
Projections that are purely exogenous
Input projections for items that are assumed to be not influenced at all by the policy response modeled within OMEGA are left as specified in the inputs. Examples might include projections of fuel prices, the state of available technology, or upstream emissions factors. While in reality these things might be influenced by the policy alternatives, we are assuming complete independence for modeling purposes, and no additional special treatment is needed for consistency.
Calibrating to projected elements that are also modeled with policy influences
Both the consumer and producer decisions will influence the modeled new vehicle sales and attributes; for example, new vehicle prices, overall sales, sales mix, technology applications, emissions rates and fuel consumption rates. While some of these elements might not be within the scope of the input projections, when a projected element is also modeled as being responsive to policy, OMEGA uses a calibration approach to maintain consistency. Specifically, after calibration, the results of a model run using the context policy will produce results that match the projections in the analysis context. If that were not the case, results for any other policy alternatives could deviate in unrealistic ways from the underlying projections.
Example: Overall sales projections and the context policy
The overall sales level is an item that is both specified as a projection in the context inputs, and is also modeled internally as responsive to changes in vehicle prices, fuel operating costs, etc. In each batch run (each batch contains two or more policy alternatives), OMEGA automatically calibrates the overall average new vehicle prices in the first session, which represents the context policy. This calibration process ensures that overall sales match the context projected sales by generating calibrated new vehicle prices (P) which are associated with the context. In subsequent sessions of the batch run for the other policy alternatives, these calibrated prices are used as the basis to which any price changes are applied (the P in equation (4.1).)
Elements not explicitly projected in new vehicle market inputs
Some elements related to vehicle attributes and sales mix may be neither part of the projection inputs nor modeled internally, yet still be important to consider in the future projections. In these cases, base year vehicle fleet attributes and relative mix characteristics are assumed to hold constant into the future.
Example: Projections for new vehicle size class mix
In this example, overall new vehicle sales projections are taken as purely exogenous. The ‘context_new_vehicle_market.csv’ file specifies the sales mix projections from AEO though 2050 by size class. As shown in Fig. 4.3, the projected sales mix of size classes varies by year, and between Context A and Context B.
All vehicle attributes which are not explicitly projected exogenously and not modeled internally are held constant from the base year fleet. For example, while size class projections are provided for overall new sales in each year, the projections are not defined at the individual producer level. Therefore, MY2019 base year relative shares of size classes for each producer are assumed to hold constant in the future. As shown in the left bar chart of Fig. 4.4, in MY2019 OEM A was more heavily focused on the Large Pickup, Small Utility, and Small Crossover classes, while OEM B was more heavily focused on the Large Utility and Midsize car classes. These relative differences between producers are maintained in the model during the process of applying the size class projections for new sales overall to the individual vehicle projections, and their associated producers, in the base year. The result is shown on the right of Figure Fig. 4.4. The combined sales of OEM A and OEM B will match the overall new sales size class shares from Fig. 4.3, while retaining the relative tendency for OEM A and OEM B to produce different size class mixes.
4.2. Policy Module
OMEGA’s primary function is to help evaluate and compare policy alternatives which may vary in terms of regulatory program structure and stringency. Because we cannot anticipate all possible policy elements in advance, the code within the Policy Module is generic, to the greatest extent possible. This leaves most of the policy definition to be defined by the user as inputs to the model. Where regulatory program elements cannot be easily provided as inputs, for example the equations used to calculate GHG target values, the code has been organized into user-definable submodules. Much like the definitions recorded in the Code of Federal Regulations (CFR), the combination of inputs and user-definable submodules must unambiguously describe the methodologies for determining vehicle-level emissions targets and certification values, as well as the accounting rules for determining how individual vehicles contribute to a manufacturer’s overall compliance determination.
Fig. 4.5 shows the flow of inputs and outputs for the Policy Module. As shown in this simple representation, the vehicle GHG targets and achieved certification values are output from the module, as a function of the attributes of candidate vehicles presented by the Producer Module.
Throughout OMEGA, policy alternatives refer only to the regulatory options that are being evaluated in a particular model run. There will also be relevant inputs and assumptions which are technically policies but are assumed to be fixed (i.e. exogenous) for a given comparison of alternatives. Such assumptions are defined by the user in the analysis context, and may reflect a combination of local, state, and federal programs that influence the transportation sector through regulatory and market-based mechanisms. For example, these exogenous context policies might include some combination of state-level mandates for zero-emissions vehicles, local restrictions or fees on ICE vehicle use, state or Federal vehicle purchase incentives, fuel taxes, or a carbon tax. A comparison of policy alternatives requires that the user specify a no-action policy (aka context policy) and one or more action alternatives.
Policy alternatives that can be defined within OMEGA fall into two categories: those that involve fleet average emissions standards with compliance based on the accounting of credits, and those that specify a required share of a specific technology. OMEGA can model either policy type as an independent alternative, or model both types together; for example, in the case of a policy which requires a minimum share of a technology while still satisfying fleet averaging requirements.
Policy alternatives involving fleet average emissions standards: In this type of policy, the key principle is that the compliance determination for a manufacturer is the result of the combined performance of all vehicles, and does not require that every vehicle achieves compliance individually. Fleet averaging in the Policy Module is based on CO2 credits as the fungible accounting currency. Each vehicle has an emissions target and an achieved certification emissions value. The difference between the target and certification emissions in absolute terms (Mg CO2) is referred to as a credit, and might be a positive or negative value that can be transferred across years, depending on the credit accounting rules defined in the policy alternative. The user-specified policy inputs can be used to define restrictions on credit averaging and banking, including limits on credit lifetime or the ability to carry a negative balance into the future. The analogy of a financial bank is useful here, and OMEGA has adopted data structures and names that mirror the familiar bank account balance and transaction logs.
OMEGA is designed so that within an analysis year, under an unrestricted fleet averaging policy, credits from all the producer’s vehicles are counted without limitations towards the producer’s credit balance. Vehicles with positive credits may contribute to offset other vehicles with negative credits. The OMEGA model calculates overall credits earned in an analysis year as the difference between the aggregate certification emissions minus the aggregate target emissions. An alternative approach of calculating overall credits as the sum of individual vehicle credits is unnecessary and in some cases may not be possible. To give one example, if a policy applies any constraints on the averaging or transfer of credits, it would not be possible to determine compliance status simply by counting each vehicle’s credit contribution fully towards the overall credits.
The transfer of credits between producers can be simulated in OMEGA by representing multiple regulated entities as a hypothetical ‘consolidated’ producer, under an assumption that there is no cost or limitation to the transfer of compliance credits among entities. OMEGA is not currently designed to explicitly model any strategic considerations involved with the transfer of credits between producers.
Emissions standards are defined in OMEGA using a range of policy elements, including:
rules for the accounting of upstream emissions
definition of compliance incentives, like multipliers
definition of regulatory classes
definition of attribute-based target function
definition of the vehicles’ assumed lifetime miles
Example: Input files for no-action and action policy definitions
Policy element |
No-action policy [Action policy] input files |
Description |
---|---|---|
Drive cycles |
drive_cycles-alt0[alt1].csv; drive_cycle_weights-alt0[alt1].csv |
Drive cycle ID’s and weights for calculating weighted average emissions from certification tests. |
Fuels |
policy_fuels-alt0[alt1].csv |
Direct and indirect CO2 values used in certification calculations for each fuel. |
GHG credit rules |
ghg_credit_params-alt0[alt1].csv |
Credit carry-forward and carry-back rules. |
GHG targets |
ghg_standards-alt0[alt1].csv |
Formula definitions for calculating g CO2/mi targets from vehicle attributes and regulatory classes. Also includes lifetime VMT assumptions. |
Offcycle credits |
offcycle_credits-alt0[alt1].csv |
Offcycle credit values for specific technologies. |
Upstream emissions accounting |
policy_fuel_upstream_methods-alt0[alt1].csv |
Selection of which methods to use for the calculation of indirect emissions certification values. |
Advanced technology multipliers |
production_multipliers-alt0[alt1].csv |
Values for multipliers used in credit calculations to incentivize the introduction of specific technologies. |
Reg classes |
regulatory_classes-alt0[alt1].csv |
Regulatory class ID’s and descriptions. |
Technology mandates |
required_sales_share-alt0[alt1].csv |
Minimum required production shares as required by the policy. |
Policy alternatives requiring specific technologies: This type of policy requires all, or a portion, of a producer’s vehicles to have particular technologies. OMEGA treats these policy requirements as constraints on the producer’s design options. This type of policy alternative input can be defined either separately, or together with a fleet averaging emissions standard; for example, a minimum Zero Emission Vehicle (ZEV) share requirement could be combined with an emissions standard where the certification emissions associated with ZEVs are counted towards the producer’s achieved compliance value.
Policy representation in the analysis context: Some policies are not modeled in OMEGA as policy alternatives, either because the policy is not aimed directly at the producer as a regulated entity, or because the particular OMEGA analysis is not attempting to evaluate the impact of that policy relative to other alternatives. However, even when a policy is not reflected in any of the analyzed policy alternatives, it may still be appropriate to represent that policy in the Analysis Context inputs. This is especially true when that external policy (or policies) might significantly influence the producer or consumer decisions. Some examples include:
Fuel tax policy
State and local ZEV policies
Vehicle purchase incentives
Investment in refueling and charging infrastructure
Accelerated vehicle retirement incentives
4.3. Producer Module
4.3.1. Producer Module Overview
The modeling of producer decisions is central to the optimization problem that OMEGA has been developed to solve. In short, the objective is to minimize the producers’ generalized costs subject to the constraints of regulatory compliance and consumer demand. The ‘producer’ is defined in OMEGA as a regulated entity that is subject to the policy alternatives being modeled, and responsible for making decisions about the attributes and pricing of new vehicles offered to consumers. A user might choose to model producers as an individual manufacturer of light duty vehicles, as a division of a single manufacturer, or as a collection of manufacturers. This choice will depend on the goals of the particular analysis, and what assumptions the user is making about the transfer of compliance credits within and between manufacturers.
Fig. 4.6 shows the flow of inputs and outputs for the Producer Module. Analysis context inputs are not influenced by the modeling within the Consumer, Producer, and Policy Modules, and are therefore considered as exogenous to OMEGA.
Inputs to the Producer Module: Policy Alternative inputs are used to calculate a compliance target for the producer (in Mg CO2) for a given analysis year using the provided attribute-based vehicle GHG targets, vehicle regulatory class definitions, and assumed lifetime VMT for compliance. Other policy inputs may define, for example, the credit lifetime for carry-forward and carry-back, or a floor on the minimum share of ZEV vehicles produced.
Analysis context inputs and assumptions that the Producer Module uses define all factors, apart from the policies under evaluation, that influence the modeled producer decisions. Key factors include the vehicle costs and emissions for the technologies and vehicle attributes considered, and the producer constraints on pricing strategy and cross-subsidization.
During the iteration process, shares of new vehicles demanded are generated by the Consumer Module as inputs to the Producer Module. These shares are at the market class-level, and based on the prices and attributes of the candidate vehicles offered by the producer in that iteration. See Section 4.5 for a description of the iteration and convergence algorithms.
Outputs of the Producer Module: During the iteration process, the outputs of the Producer Module describe the candidate vehicles – prices, quantities, and key attributes – which forms the basis for determining compliance status (by iterating with the Policy Module) and demanded sales shares (by iterating with the Consumer Module.) Once model convergence is achieved, the Producer Module outputs the details of the produced vehicles.
4.3.2. Producer Compliance Strategy
The Producer Module simulates decisions about vehicle design, pricing, and production quantities that minimize compliance costs while satisfying other considerations imposed by the policy, consumers, and production constraints. With a fleet averaging policy that allows credit banking and trading, the producer is making these product decisions within an overall strategy of managing compliance credits from year-to-year.
Vehicle design strategy
While the producer’s modeled objective function is cost minimization, the term ‘cost’ is used generically here, as it is not necessarily the case that the lowest production cost option is the best option for the producer. Consumer willingness to pay for a particular vehicle attribute can result in another choice if the producer expects that the additional production costs can be more than offset by a higher price. Here, the term producer generalized costs is defined as the net of vehicle production costs and the producer’s view of consumer’s willingness to pay for that vehicle.
The Producer Module will first attempt to select the available vehicle design options (i.e. tech package applications) and sales mix that minimizes generalized costs while meeting the strategic compliance target (Mg CO2e.) This is the starting point of an iterative process, since in many cases the demand estimated by the Consumer Module will not match this first set of vehicle attributes, prices, and quantities within the desired convergence tolerance.
Vehicle pricing and sales mix strategy
In addition to influencing key vehicle attributes by the design decisions, the producer also has some flexibility in how vehicle prices are set. Using cross-subsidization strategies to spur greater sales of some vehicles at the expense of others, producers can incentivize market class sales mix changes in order to reduce generalized costs. This assumption that producers will attempt to minimize their generalized costs is consistent with a producer goal of profit maximization.
In reality, there are limits to the ability of producers to adjust vehicle prices. The user can define upper and lower limits to how much price cross-subsidization can be applied. Also, the model automatically only searches for solutions that maintain the overall average vehicle price, thus forcing any cross-subsidization strategies to be revenue neutral.
Credit management strategy
With a policy that allows credit banking, the efficient management of compliance credits from year-to-year involves a degree of look-ahead, both in terms of expected changes in regulatory stringency and other policies, and expected changes in generalized costs over time. At this time, OMEGA assumes that producers aim to meet the GHG target in each year, with any banked credits used only to make up differences between the certification and target values. The producer logic associated with the process box labeled “Determine Strategic Target Offset” in the process flow diagram (Fig. 4.2) therefore simply applies the offset, if any, to the policy GHG target.
4.3.3. Vehicle Definitions
The vehicle is the fundamental unit of analysis within the Producer Module, and the decisions made by producers determine the vehicle attributes and sales in the modeled results. The vehicle resolution is determined by the user (see Section 4.1.1) consistent with the resolution defined in the base year vehicles input file. Depending on the focus of a particular run, vehicles might be defined at a market class level using an aggregate representation over multiple producers, or at the nameplate or even subconfiguration level.
Along with a definition of resolution, the base year vehicles inputs also define the key exogenous attributes that are necessary for 1) generating future projections, 2) assigning the policy emissions targets, 3) estimating consumer demanded quantities, 4) determining appropriate emissions rates and costs from the applied technology packages.
Example: Vehicle definitions in base year fleet
Field Name |
Attribute Required For: |
Example 1 |
Example 2 |
Example 3 |
Example 4 |
---|---|---|---|---|---|
vehicle_name |
tracking of producer decisions in modeled results |
ICE Large car |
ICE Large Crossover truck |
ICE-HEV Large Pickup truck 4WD |
ICE Large Van truck minivan 4WD |
manufacturer_id |
grouping for producer modeling |
OEM_B |
OEM_A |
OEM_A |
OEM_A |
model_year |
determination of analysis start year |
2019 |
2019 |
2019 |
2019 |
reg_class_id |
reference (assigned by policy in analysis timeframe) |
car |
truck |
truck |
truck |
epa_size_class |
reference |
Large Cars |
Standard SUV 2WD |
Standard Pick-up Trucks 4WD |
Special Purpose Vehicle, minivan 4WD |
context_size_class |
sales mix projections |
Large |
Large Crossover |
Large Pickup |
Large Van |
electrification_class |
reference (modeled element in analysis timeframe) |
N |
N |
HEV |
N |
cost_curve_class |
cost and emissions rates for tech packages |
ice_MPW_LRL |
ice_MPW_HRL |
ice_Truck |
ice_MPW_HRL |
in_use_fuel_id |
reference (modeled element in analysis timeframe) |
{‘pump gasoline’:1.0} |
{‘pump gasoline’:1.0} |
{‘pump gasoline’:1.0} |
{‘pump gasoline’:1.0} |
cert_fuel_id |
reference (modeled element in analysis timeframe) |
{‘gasoline’:1.0} |
{‘gasoline’:1.0} |
{‘gasoline’:1.0} |
{‘gasoline’:1.0} |
sales |
sales mix projections |
536531 |
496834 |
78297 |
13795 |
cert_direct_oncycle_co2e_grams_per_mile |
reference (modeled element in analysis timeframe) |
345.3 |
418.6 |
405.8 |
403.0 |
cert_direct_oncycle_kwh_per_mile |
reference (modeled element in analysis timeframe) |
0 |
0 |
0 |
0 |
footprint_ft2 |
policy targets (‘Alternative 0’ only) |
50.5 |
54.7 |
68.5 |
56.0 |
eng_rated_hp |
reference (modeled element in analysis timeframe) |
268 |
318 |
364 |
296 |
tot_road_load_hp |
reference (modeled element in analysis timeframe) |
12.5 |
16.1 |
19.3 |
17.3 |
etw_lbs |
reference (modeled element in analysis timeframe) |
4035 |
5095 |
5518 |
5000 |
length_in |
reference |
195.3 |
201.6 |
231.6 |
200.6 |
width_in |
reference |
73.8 |
78.0 |
80.6 |
78.1 |
height_in |
reference |
58.2 |
71.1 |
77.0 |
70.4 |
ground_clearance_in |
reference |
5.2 |
8.3 |
6.5 |
|
wheelbase_in |
reference |
114.0 |
118.4 |
143.1 |
119.3 |
interior_volume_cuft |
reference |
148.3 |
|||
msrp_dollars |
reference (modeled element in analysis timeframe) |
42554 |
46592 |
40740 |
39962 |
passenger_capacity |
policy targets (‘Alternative 1’ only) |
5.0 |
6.6 |
5.5 |
7.0 |
payload_capacity_lbs |
reference |
1030 |
1438 |
1748 |
|
towing_capacity_lbs |
reference |
1000 |
5598 |
10509 |
3500 |
unibody_structure |
reference |
1 |
1 |
0 |
1 |
4.3.4. Vehicle Simulation and Cost Inputs
One of the most important sets of inputs to the Producer Module is the simulated vehicles file. It contains the vehicle parameters used by OMEGA to generate all possible vehicle technology (and cost) options available to the producers – these production options represent distinct points in what might be considered a point ‘cloud’. The use of these vehicle clouds by OMEGA is described in Section 4.3.5.
The simulated vehicle file contains the various vehicles of different core attributes (such as vehicle size, weight, powertrain, etc), the CO2-reducing technologies that are applied to each, and their predicted energy consumption, CO2 performance, and cost. While not required by all users, EPA uses its own simulation tool (ALPHA) to predict the energy consumption and CO2 emissions for each vehicle and technology combination. For this example, these vehicle and technology options (and associated CO2 performance) are consolidated into the ‘simulated_vehicles.csv’ file. The simulated vehicles file contains the following fields for use in the Producer Module:
the associated cost curve class (defined by powertrain family and described below)
vehicle properties such as curb weight, type of base powertrain (ICE/HEV/PHEV/BEV, etc)
other included technologies (e.g., A/C credits, high efficiency alternator, etc)
test cycle performance (energy consumption (for plug-in vehicles) and/or CO2 emissions)
vehicle attributes, such as included technologies, costs
Significance of the cost curve class: Each cost curve class includes multiple vehicles and represents the design space for all vehicle options in each class. In this example, multiple vehicles are grouped within a single cost curve class to reduce the number of simulations required to represent the design space. OMEGA producer decisions are made based on discrete vehicle options within each vehicle cost curve class. For possible future consideration, EPA recommends the generation of RSEs (response surface equations) to derive particular cost clouds unique to each vehicle. This would allow for more unique cost and vehicle clouds without excessive simulation calculation burden.
4.3.5. Vehicle Cost Clouds, Cost Curves, and Aggregation
The technology packages and their application to candidate vehicles are described in the model inputs as a discrete set of options that were generated using tools and approaches external to OMEGA (e.g. vehicle simulation, benchmarking, cost teardowns, etc.) Because the product design problem being solved is multi-dimensional (i.e. an intersection of technology package applications and market share decisions for multiple vehicles), the choice set must be built up from various combinations of vehicle-level decisions that cannot be readily predicted in advance.
The Producer Module uses an approach of aggregating the discrete, vehicle-level decisions at several levels, while retaining the vehicle-specific information that can be accessed later in other stages of the modeling and presented in the results. These processes of vehicle aggregation (also referred to as composition or the creation of “composite vehicles”) and decomposition are critical for the solution search process. First, aggregation allows the model to efficiently search for a solution without a complete enumeration of all possible choice combinations. Second, decomposition allows the model to draw upon the key vehicle attribute details that have been retained and are required for calculating the compliance emissions values and estimating the consumer response.
Vehicle-level technology application options
In oder to minimize cost, a producer would need to select the minimum cost package available at a given compliance emissions rate (i.e. g CO2/mi.) This subset of cost-minimizing vehicle technology packages is referred to as the cost curve, while the broader set of points is the cost cloud. Note that ‘cost’ here is referring to the producer generalized cost, as explained in Section 4.3.2.
Example: Vehicle cost clouds
An example cost cloud for a single vehicle in MY2025 (vehicle #62, a 4WD minivan) for the no-action policy in Context A is shown in Fig. 4.7. The costs for the blue points are production costs. The orange point costs are producer generalized costs, and include 5 years of fuel costs at 15,000 miles per year that the producer assumes are valued by consumers at the time of purchase (as defined in the analysis context input file ‘producer_generalized_costs.csv’.) Note that the producer generalized costs are higher than the production costs, and also form a cloud with a different shape than the blue production cost cloud. Essentially, the orange cloud is shifted up and rotated counterclockwise relative to the blue cloud because the technology packages with higher emissions rates also have relatively higher fuel costs that are assumed to factor into consumer purchases.
Fig. 4.7 also contains the resultant cost curve (black line) that represents the cost-minimizing frontier of the cost cloud. The Producer Module automatically generates this piece-wise linear approximation of the frontier using points in the cloud.
Compliance options based on design decisions across multiple vehicles
Because a producer can offer a range of different vehicles, each with distinct costs associated with applying technology packages, it is not likely that the lowest cost compliance solution will be a uniform application of technology to all vehicles. Nor will selecting the lowest cost option for each vehicle likely result in producer compliance, except in cases where a policy is non-binding. In order to consider design options for multiple vehicles simultaneously, the Producer Module aggregates individual vehicles into composites, with one composite vehicle for each market class and reg class combination. It is important that the resultant cost curves (producer generalized cost vs. g CO2/mi emissions rates) are not aggregated further since 1) aggregating emissions rates across market classes would no longer be valid after iteration when the Consumer Module changes the relative shares of market classes, and 2) aggregating emissions rates across regulatory classes would, under some policy definitions, make it impossible to calculate the Mg CO2 compliance credits (e.g. in policy cases where there are limits to the transfer of credits between regulatory classes.)
Example: Vehicle aggregation into market class - reg class cost curves
Fig. 4.8 shows the black cost curve of veh #62 as presented in Fig. 4.7, along with the other vehicles that are in the same combination of market class (ICE non-hauling) and reg class (‘a’.) Note that the simulated_vehicles.csv file for this example does not contain distinct costs and emissions rates for every vehicle. As a result, even though there are 12 vehicles are represented here, they overlay into only three distinct cost curves. If a user provided simulated_vehicles.csv inputs defined with greater resolution, every vehicle could be associated with its own distinct cost curve.
The bold orange line in Fig. 4.8 is the MY2025 cost minimizing frontier for a composite vehicle made by aggregating the individual vehicle cost curves in the same market class and reg class combination. The relative shares of vehicles within a market class and reg class remain fixed in the Producer-Consumer iteration process. Therefore the composite vehicle cost curve does not change as a result of the consumer response. This curve, along with the composite vehicle cost curves from the other market class and reg class combinations, is used to generate the producer compliance options.
Once composite vehicle cost curves are generated for each market class and reg class combination, the Producer Module creates compliance options from a combination of design choices for the relative shares of composite vehicles and the emissions rate of each composite vehicle. The resulting compliance options are defined in terms of cost vs. Mg CO2 credits rather than g CO2/mi. See Section 4.5 (iteration and convergence) for more discussion of how the model converges on a solution by searching among these compliance options, and generating interpolated compliance options that are successively more refined with each iteration.
Extracting key vehicle attributes from the composite vehicles through decomposition
Once a compliance option is selected through the iteration and convergence process, a user will likely want to know how specific vehicle design decisions contributed to that solution.
Example: Decomposition of composite vehicle
Because the composite vehicle is made up of individual vehicles of fixed sales shares (at least relative to the other vehicles in the same market class, reg class combination), there is one-and-only-one solution for individual vehicle costs and emissions rates that will result in the selected option for the composite vehicle’s cost and emissions rate. Fig. 4.9 shows the same orange composite vehicle curve from Fig. 4.8, along with star symbols to indicate the selected option for the composite vehicle and associated points for the individual vehicles.
4.4. Consumer Module
The Consumer Module is a significant addition to OMEGA. With the ongoing evolutions in the light-duty vehicle market, including major growth in technologies and services, the need for an endogenous consumer response is clear. The Consumer Module is structured to project how consumers of light-duty vehicles would respond to policy-driven changes in new vehicle prices, fuel operating costs, trip fees for ride hailing services, and other consumer-facing elements. The module is set up to allow the inputs to affect total new vehicle sales (both in number and proportion of sales attributes to different market classes), total vehicle stock (including how the used vehicle market responds), and total vehicle use (the VMT of the stock of vehicles).
An important consideration with the addition of the Consumer Module is ensuring consistency between the set of vehicles and their attributes that the Producer Module supplies and the set of vehicles and their attributes that the Consumer Module demands. In order to estimate the set of new vehicles that provide this equilibrium, the Consumer and Producer modules iterate until convergence is achieved - where the set of vehicles, including their prices and attributes, that satisfy producers is the same set of vehicles that satisfy consumers.
4.4.1. Consumer Module Overview
As explained in the Overview chapter, and shown in Fig. 1.1, OMEGA is structured in a modular format. This means that each primary module — the Policy Module, Producer Module, Consumer Module and Effects Module — can be changed without requiring code changes in other modules. This ensures users can update model assumptions and methods while preserving the consistency and functionality of OMEGA.
An overview of the Consumer Module can be seen in Fig. 4.10. This overview shows the connections between the Consumer Module, the analysis context, and other OMEGA modules. The Consumer Module receives inputs from the analysis context and the Producer Module, and computes outputs used in iteration with the Producer Module and for use in the Effects Module.
The Consumer Module’s purpose is to estimate how light duty vehicle ownership and use respond to key vehicle characteristics within a given analysis context. There are five main user-definable elements estimated within the Consumer Module, as seen in Fig. 4.11. These estimates are: market class definitions, new sales volumes, new vehicle sales shares by market class (where market classes depend on the requirements of the specific consumer decision approach used in the analysis), used vehicle market responses (including reregistration), and new and used vehicle use measured using vehicle miles traveled (VMT). Further explanations of each of these elements are described in the following sections.
Each of these five elements represents a user-definable submodule within the Consumer Module code. The code within each submodule may be updated by a user, or the submodule may be replaced with an alternative submodule. When a modifies a submodule, they must ensure that the submodule retains consistency with the other submodules within the Consumer Module, as well as with the rest of OMEGA. For example, if the market class submodule is changed, the sales share submodule must be updated as well since sales shares are determined by market class.
Example: Consumer Module user-definable submodules
The user-definable submodules of the Consumer Module in this example are listed in the table below.
Element |
Submodule |
---|---|
Market class definitions |
market_classes.py |
New vehicle sales volume |
sales_volume.py |
New vehicle sales shares |
sales_share.py |
Used vehicle reregistration |
reregistration_fixed_by_age.py |
New and used vehicle use |
annual_vmt_fixed_by_age.py |
The Consumer Module works in two phases: first, an iterative new vehicle phase, followed by a non-iterative stock and use phase. During the first phase, the Consumer Module and Producer Module iterate to achieve convergence on the estimates of new vehicles produced and demanded that meet the standards set in the Policy Module. The Producer Module sends a set of candidate vehicles, including their prices and attributes, to the Consumer Module to consider. The Consumer Module uses that set of candidate vehicles to estimate total new vehicles demanded and the shares of those new vehicles in the specified market classes, which are passed back to the Producer Module. If the estimates do not converge within a tolerance, a new set of candidate vehicles is sent to the Consumer Module for consideration. See Section 4.5 for more information on the Consumer-Producer iteration process. Once convergence between the Producer and Consumer modules is achieved, the set of candidate vehicles are no longer considered candidates for consideration, but are the estimated new vehicle fleet, and the Consumer Module enters the second phase. In this phase, total vehicle stock (new and used vehicles and their attributes) and use (VMT) are estimated.
Inputs to the Consumer Module In general, the Consumer Module uses exogenous inputs from the analysis context, and endogenous inputs from the Producer Module. The exogenous inputs may include data such as fuel prices, existing vehicle stock, and specific modeling parameters, for example, the parameters used in estimations of vehicle ownership and use decisions. The analysis context must also contain the inputs required to define projections of vehicle ownership and use in the absence of any policy alternatives being analyzed. These projections might be provided directly as inputs to the Consumer Module, such as projections of vehicle ownership from the Annual Energy Outlook (AEO), or generated within the Consumer Module based on exogenous inputs, including future demographic or macroeconomic trends. Endogenous inputs are factors determined within the model and passed to the Consumer Module from the Producer Module. They may include vehicle prices and other relevant vehicle attributes, such as fuel consumption rate. Because the Consumer Module’s internal representation of consumer decisions can be defined by the user, the specific exogenous and endogenous inputs required will depend on the models, methods, and assumptions specified by the user. The vehicle attributes needed as inputs to the Consumer Module are determined by the methods used to estimate new vehicle sales, the market shares of vehicles demanded, used vehicle reregistration, and new and used vehicle use. For example, vehicle attributes used to define market classes must be included as inputs from the Producer Module. As an additional example, if the user defines vehicle sales responses to differ based on consumer income, the user must ensure that income is included in the analysis context inputs.
Outputs of the Consumer Module The Consumer Module produces two categories of outputs: sales estimates during the iterative Phase 1, and stock and use estimates during the non-iterative Phase 2. During the iterative phase, outputs of the Consumer Module, including new vehicle sales and responsive market shares (explained in the following section), are fed back to the Producer Module for iteration and convergence. See Section 4.4.3 for more information on what happens during Phase 1, and Section 4.5 for more detailed information on how OMEGA estimates iteration and convergence between the Producer and Consumer modules. Once that convergence is achieved, the Consumer Module estimates the outputs of the stock of vehicles, including both new and reregistered used vehicles, and VMT, which are used by the Effects Module.
4.4.2. Market Class Definitions
During the iterative first phase, the Consumer Module considers vehicle prices and attributes at an aggregate level by grouping vehicles into market classes. These market classes are the fundamental unit of analysis for which the Consumer Module estimates new vehicle sales and shares. The choice of market classes is tied to the specification used to estimate the shares of new vehicles sold, and is dependent on the attributes available in the input data files. For example, vehicles might be identified by attributes such as fuel type (electric, gas, diesel, etc.), expected use (primarily for goods or passenger transport), or size.
Users can define market classes in the market class definitions submodule (as shown in Fig. 4.11.) In doing so, the user must ensure that all other inputs and user-definable submodules (for example, with respect to stock and use estimation) within the Consumer Module are defined consistently. For example, if the sales share submodule is defined as estimating shares of vehicles in a set of fuel type categories, those fuel type categories must be defined within the market class submodule.
The designation of market classes can be used to reflect market heterogeneity in purchasing behavior or vehicle use based on specific vehicle attributes. Accordingly, market classes are defined using vehicle attributes and inputs from the analysis context (i.e. the base year vehicle inputs.) In addition, the user can categorize market classes as ‘responsive,’ where the shares of total vehicles attributed to those market classes change due to endogenously modeled elements that change in response to policy (like relative costs), or ‘nonresponsive,’ where the shares of total vehicles attributed to those market classes do not change with the policy being analyzed.
Before the Consumer Module can estimate new vehicle sales or market shares responses, all vehicles must be categorized into their market classes. This categorization is defined as a series of nested market category levels. The user can define any number of market classes, or levels, as well as the hierarchy of the levels. In defining the hierarchy, it is important to note that OMEGA assumes that the sales share estimates within a parent category are independent of sales share estimates outside the parent category. This means that changing the available market classes outside the parent category will not change the sales share estimates within the parent category.
Example: Market class structure
Fig. 4.12 below illustrates the nested market class hierarchy used in this example. Hauling/non-hauling market classes are the highest, parent, level. Vehicles are separated into the appropriate hauling and non-hauling class using their attributes. Nested within the hauling and non-hauling categories, there are BEV/ICE market classes. The candidate vehicle inputs from the Producer Module, for example, vehicle prices, fuel cost and VMT, are used to determine the share of vehicles in the BEV/ICE market classes, as described in the examples below. During the iterative first phase, if the share of BEVs that consumers will accept given the candidate vehicle attributes does not converge within a tolerance with the share that the Producer Module estimates, the iterative process continues. The demanded BEV share is passed back to the Producer Module, which will return a new set of candidate vehicles and their attributes, including prices. Given the updated candidate vehicle inputs, the Consumer Module will redistribute vehicles into the BEV and ICE classes, with the BEV/ICE share estimates in the hauling category being independent from those in the non-hauling category. This possible redistribution between market class categories is represented by the dashed lines between each set of BEV/ICE classes. Note that the dashed lines travel within the hauling class and within the non-hauling class, but do not travel across them.
Within a given analysis context, the shares of vehicles allocated to nonresponsive market class categories do not shift between those nonresponsive market categories, even under different policy alternatives or during iteration with the Producer Module. Shares of vehicles allocated to responsive market class categories may shift between the responsive market categories.
Example: Nonresponsive and responsive market classes
Within the example analysis, vehicles are separated into four market classes depending on whether they are categorized as hauling (primarily meant for transporting goods or towing, as a body-on-frame vehicle would be expected to do) or non-hauling (primarily meant for passenger transportation, as a unibody vehicle might do), and their fuel type (battery electric vehicle (BEV) or internal combustion engine vehicles (ICE)). The hauling/non-hauling market classes are defined as nonresponsive market class categories. The share of vehicles defined as hauling or non-hauling, regardless of the fuel type, depends on analysis context inputs, and is unaffected by model results. The BEV/ICE market classes are defined as responsive market class categories, the share of vehicles in that market class is estimated within the Consumer Module and is responsive to vehicle cost and fuel consumption rate of the set of candidate vehicles input from the Producer Module.
4.4.3. Phase 1: Producer-Consumer Iteration
During the iterative first phase of the Consumer Module, the Producer Module and Consumer Module iterate to estimate total new vehicle sales, market shares, and prices at the market class level, based on the candidate vehicle options being offered by the producer. The iteration process is described more fully in the Iteration and Convergence Algorithms section. It begins with the Producer Module providing a set of candidate vehicles that meet the policy targets as defined within the Policy Module while minimizing the producer’s generalized costs. At this initial step, overall volumes are taken directly from the analysis context projections, along with sales shares projection of nonresponsive market class categories. If the sales and market shares result estimated within the Consumer Module is not within a given threshold of the estimates from the Producer Module, iteration between the modules occurs. The process entails the Producer Module offering successive sets of candidate vehicles and their attributes, including prices, which still achieve the policy targets until a there is set of candidate vehicles which results in agreement between the Producer Module and Consumer Module estimates of sales and market shares, or until an iteration limit is reached. On the Producer Module side, the process also includes determining the level of cross-subsidization between vehicle classes, which is covered more fully in the Iteration and Convergence Algorithms section. Within this iterative first phase of the Consumer Module, there are two main determinations being made: the total sales volume consumers will accept, and the share of vehicles they demand from each market class. Much of the method and assumptions used to estimate sales and shares impacts can be defined by the user in the New Vehicle Sales Volumes and New Vehicle Sales Shares submodule as seen in Fig. 4.11, including the method of estimating a change in sales volumes or responsive market shares, consumer responsiveness to price, and what is included in the price consumers take into account.
Sales volumes
The Consumer Module estimates the total new vehicles sold at the aggregated market class level with the user-definable submodule for new vehicle sales. The estimate for the change in new vehicle sales starts with an assumption of sales volumes in the Context Policy (the “no-action alternative”). These estimates can be an exogenous input from the analysis context, or estimated within the Consumer Module. Sales volumes under a defined policy (an “action alternative”) can be responsive to policy if the estimation is defined as relying, at least in part, on inputs from the Producer Module, or may be unresponsive to policy if the estimation is defined to rely solely on inputs from the analysis context. In defining how the Consumer Module estimates sales volumes, the user must ensure consistency between the inputs available from both the Producer Module and the analysis context, as well as with the other user-definable submodules within the Consumer Module. For example, if a user defines sales volumes as responsive to a specific vehicle attribute, that attribute must be included in the set of candidate vehicles and their attributes input from the Producer Module.
Example: New vehicle sales estimates
In the example analysis, sales volumes under the no-action policy alternative, which is also the Context Policy, are an exogenous input from the analysis context. An elasticity of demand, defined by the user, is used in conjunction with the change in price between a no-action alternative and an action alternative to estimate the change in sales from the no-action alternative level. Demand elasticity is defined as the percent change in the quantity of a good demanded for a 1% change in the price of that good, where the good demanded in the Consumer Module is new light duty vehicles. They are almost always negative: as the price of a good increases (a positive denominator), the amount of that good purchased falls (a negative numerator). Larger (in absolute value) negative values are associated with more “elastic”, or larger, changes in demand for a given change in price. This value represents how responsive consumers are to a change in price. The general elasticity equation is:
(4.1)
Where:
is the elasticity of demand
is the change in the quantity demanded
is the quantity demanded before the price changes
is the change in the good’s price
is the good’s price before the change
In the example analysis, the default elasticity of demand is set to -1. This means, for a 1% change in the consumer generalized price (described below), the vehicles demanded by consumers will fall by 1%. In order to estimate the change in sales expected as function of the estimated change in price, this equation is rearranged:
(4.2)
At an aggregate level, the average expected change in the price of new vehicles is multiplied by the defined demand elasticity to get the estimated change in vehicles demanded. This change is combined with projected new vehicle sales under the no-action alternative to get the total new vehicle sales under the action alternative outlined in the Policy Module.
If a user adopts the example analysis method of estimating sales volumes using an elasticity of demand, they must ensure that net vehicle price, P, is defined. This net price is estimated under the no-action and the action alternatives, and the no-action alternative net price is subtracted from the action alternative net price to get an estimated change in net price, , that can be used with the user-specified elasticity. The net price should include factors the user assumes consumers consider in their purchase decision. Some factors that might be included are the share of total costs the producers pass onto the consumers, and the amount of future fuel costs consumers consider in their purchase decision.
Example: Net price
In the example analysis, the net price value in the sales volume estimate includes assumptions about the share of the total cost that producers pass onto the consumer and the amount of fuel consumption considered in the purchase decision. With respect to the share of total cost that producers pass onto consumers, this example assumes “full cost pass-through.” This means that the full increase in cost that producers are subject to in achieving emission reduction targets is passed on to the consumers. However, due to cross-subsidization, those costs may be spread across multiple market classes.
The role of fuel consumption in the purchase decision is represented by the number of years of fuel consumption consumers consider when purchasing a new vehicle, and can range from 0 through the full lifetime of the vehicle. Fuel costs are estimated using vehicle fuel consumption rates from the Producer Module, projections of fuel prices from the analysis context, the user-specified VMT schedules, and the user-specified vehicle reregistration schedules. The resulting portion of fuel costs considered by consumers is added to the candidate vehicle prices from the Producer Module to produce a net vehicle price, which is then used in conjunction with the elasticity of demand to estimate the change in vehicle sales. This example analysis assumes that consumers consider 5 years of fuel costs in the vehicle purchase decision.
Sales shares
The new vehicles sold are categorized into the user-definable market classes using estimates of sales shares. As mentioned above, those market classes can be nonresponsive or responsive to the policy being analyzed. Nonresponsive vehicle shares do not change with updated candidate vehicle sets or across policy alternatives. Though not responsive to endogenous inputs, the nonresponsive sales shares do not have to be constant. For example, they may be provided as a set of values for different points in time if the shares are expected to change exogenously over time. In addition, users can define sales shares to explicitly consider consumer heterogeneity by defining separate sales share estimates for different consumer groups. For example, sales share responses can differ between rural and urban consumers. If users identify heterogenous consumer groups with separate sales share responses, the analysis context must include the appropriate inputs. For example, the proportion of the vehicle buying population in urban and rural areas for each year being analyzed within the model.
For responsive market classes, users can define how market shares are responsive to attributes of candidate vehicle sets fed in from the Producer Module, for example vehicle price. In addition, the inputs used to estimate shares must be available within the set of candidate vehicles and their attributes, or as part of the analysis context.
If the user retains the method of determining responsive BEV shares (using a logit curve as described above), the parameters representing the speed of acceptance, , and price responsiveness, , are factors the user can modify in the sales share submodule inputs (see sales share inputs
)
In addition, the user must specify the price used in the logit equation. This price should include factors the user estimates are significant in determining relative market shares; cost factors can be monetary, such as capital and maintenance costs, or non-monetary, such as time. In addition, price estimation needs to be consistent with the speed of acceptance and price responsiveness parameters.
4.4.4. Phase 2: Vehicle Stock and Use
If convergence with respect to the sales and shares of new vehicles is achieved, the Consumer Module estimates total vehicle stock and use. To do so, it needs to keep internal consistency between- the number of vehicles demanded and the use of those vehicles. The method of determining total vehicle stock and vehicle use are in user-definable submodules represented by the used vehicle market response element and the new and used vehicle use element in Fig. 4.11. Vehicle stock is the total onroad registered fleet, including both new vehicles sales and the reregistered (used) vehicles. The data contained in the set of vehicle stock includes both vehicle count, as well as the attributes of the vehicles in the set, including model year and the vehicle features or attributes used to designate market classes. Vehicle use is the measure of how much each vehicle is driven in the analysis year, measured in vehicle miles traveled (VMT). VMT is determined at the vehicle level.
Vehicle stock
Fig. 4.13 below steps through the flow of how total vehicle stock is estimated in OMEGA. To estimate vehicle stock, the model starts with a base year stock of vehicles, which is an input from the analysis context. The base year is the last year actual observations, and is unmodified during the analysis. The analysis start year is the first year in which modeling is performed and immediately follows the base year. The stock of vehicles at the end of the analysis start year includes the new vehicles produced, plus the set of vehicles that were reregistered from the base year stock. For each subsequent modeled (analysis) year, the total stock is determined from the new vehicles produced in that year plus the reregistered vehicles from the prior year.
The method of estimating the reregistered fleet is in a user-definable used vehicle reregistration submodule. This method can make use of a static schedule, for example, where a vehicle’s age is the only determinant of the proportion of vehicles remaining in the fleet over time, or depend on other vehicle attributes, like cumulative VMT. If users modify the reregistration submodule to follow a different prescribed static rate, or to allow interdependencies between the rate of reregistration and other vehicle attributes, they need to retain consistency between the reregistration submodule and other submodules, for example the submodules estimating new vehicle sales and total VMT.
Example: Vehicle stock estimates
In this example analysis, the analysis start year stock of vehicles comes from the analysis context, and reregistration is estimated using fixed schedules based on vehicle age. For every calendar year, a specified proportion of vehicles in each model year is assumed to be reregistered for use in the following calendar year. In this fixed schedule, the proportion of vehicles of a given model year remaining in the registered stock (i.e. the survival rate) falls as the vehicles age. For example, in 2030, the proportion of the original MY 2025 vehicles remaining is larger than the proportion of MY 2015 vehicles remaining.
Vehicle use
Vehicle use is estimated as the vehicle miles traveled for each vehicle in the stock for the analysis year. This can be thought of as a measure of consumer demand for mobility. The method of estimating total VMT for the stock of vehicles is in a user-definable new and used vehicle use submodule. VMT can be estimated simply as a function of vehicle age, or may be a function of age, market class, analysis context inputs or more. Use could also include estimates of rebound driving. Rebound driving is estimated as the additional VMT consumers might drive as a function of reduced cost of driving.
Example: VMT estimates
In this example analysis, total VMT demanded is an input from the analysis context and is constant across policy alternatives. Total VMT demanded is combined with the initial stock of vehicles and their attributes from the analysis context to determine the proportion of VMT attributed to cohorts of vehicles separated by age and market class. For each calendar year, the total VMT projected in the analysis context is allocated across the internally estimated stock of vehicles using this fixed relationship. This method allows VMT per vehicle to change with the total stock of vehicles, while assuming that consumer demand for mobility is not affected by the action alternatives under consideration.
4.5. Iteration and Convergence Algorithms
OMEGA finds a solution in each analysis year using iterative search algorithms. As shown in the process flow diagram in Fig. 4.2, the model uses two iterative loops; a Producer-Policy loop and a Producer-Consumer loop. For both loops, convergence criteria must be achieved within a specified tolerance for the simulation to proceed. This section describes those loops in more detail, with additional information from an example.
‘Producer-Policy’ Iteration: Compliance Search
The iteration process begins with a search for the vehicle design options and market class shares that minimize producer generalized costs and achieve the desired compliance outcome, independent of any feedback from the Consumer Module regarding vehicle demand. In this step, individual compliance options are built up, with each option fully defining the shares of each market class, and the technology package applications on each of the producer’s vehicles. From all these compliance options, up to a pair of points is selected which are closest, above and below, to the strategic GHG target (i.e. Mg CO2e.). If all points are under- or over-target then the point nearest to the target is chosen. The market shares and technologies of the selected point(s) become seed values for the next sub-iteration. In each successive sub-iteration, the search area becomes narrower while also covering the options with greater resolution. Finally, when a point falls below the convergence tolerance for Mg CO2 credits or the search range has fallen below a minimum tolerance, the closest point is selected as the compliance option for the initial compliance search.
Example: Initial compliance search
Fig. 4.14 shows the various sub-iterations for the initial compliance search in this example for 2025. The left figure shows a number of blue points for the 0th sub-iteration. The two low cost points nearest to 0 Mg CO2e credits form the basis for the search in the next sub-iteration. The right figure show all 15 sub-iterations (0th to 14th), including the points selected in the 0th sub-iteration (blue stars.) Note that the sub-iterations shown by the colored gradient scale have progressively lower costs, and more closely focused around 0 Mg CO2e. The selected compliance option from the initial Producer-Policy compliance search is shown by a single red star.
Fig. 4.15 is another view of the same search, with greater magnification around the selected production option and surrounding options which were not selected.
‘Producer-Consumer’ Iteration: Market Shares and Pricing
After a purely cost-minimizing option is selected in the initial compliance search, the Producer Module provides the vehicle attributes and prices, at the market class level, for consideration by the Consumer Module. Within a given Producer-Consumer iteration loop, the vehicle design options are fixed. The search for a solution is based on consideration of various market class share and pricing options. Criteria for convergence include 1) the percent change in average total price, and 2) the difference in the producer and consumer market shares. To achieve convergence, both of these metrics must be close to zero, within the specified tolerance.
Example: Consumer-Producer iteration
Within a single Producer-Consumer iteration loop, vehicle designs are fixed, but pricing and market class shares vary. Fig. 4.16 shows the various components of the first Producer-Consumer iteration loop for 2025 in this example (Context A, no action policy alternative.)
The upper left panel shows the range of producer cross-subsidy price multiplier options. The full range of multipliers in the 0th sub-iteration are dark blue points, which then narrow in range over eight sub-iterations. The final range of multipliers is shown by the red points.
In the upper right panel, those same pricing options are shown in terms of absolute prices. While the multipliers applied to hauling and non-hauling vehicles cover a similar range of values, the lower absolute prices for non-hauling vehicles results in a range of prices that is somewhat narrower than the range for hauling vehicles.
The two convergence criteria are illustrated in the bottom two panels of Fig. 4.16 (share delta for hauling BEVs in the lower left panel, and average total price delta in the lower right panel.) In this Producer-Consumer iteration, the market class shares offered by the producer do not converge with the shares demanded by the consumer over the range of cross-subsidy pricing options available. This is visible in the lower left panel, since the 0.4% share delta value in the final sub-iteration does not meet the convergence criteria. If convergence had been achieved, the iteration process of this analysis year would be complete, and the produced vehicles would be finalized. Otherwise, the iteration will proceed, with a new consideration of vehicle design options offered by the Producer Module.
Repeat Iteration of ‘Producer-Policy’ and ‘Producer-Consumer’
If the prior round of iterations is unable to find a converged solution, the process will continue by repeating a series of Producer-Policy compliance searches and Producer-Consumer market share and pricing searches. The process is the same as in the initial iteration, with one exception: that the Producer-Policy compliance search will use the market shares from the prior iteration’s Producer-Consumer search.
These iterations are repeated until the market class share and average total price convergence criteria are met, and the compliance search is complete. Alternatively, if the number of Producer-Consumer iterations exceeds the set limit, then the sales and market shares from the last iteration are used. In this case, any deviation from the Producer’s strategic compliance target in that analysis year must be made up for through the use of banked credits. Finally, the produced vehicles are logged for consideration in the Consumer Module’s vehicle stock and use submodules, and in the Effects Module.
Example: First iteration beyond initial Producer-Policy and Producer-Consumer iterations
Fig. 4.17 shows the points considered in the compliance search in the first iteration (2025_1) following the initial iteration(2025_0). Similar to the initial iteration, each point represents a compliance option that is the result of a unique combination of candidate vehicle design choices and market class shares. Note that compared to Fig. 4.14, the points in Fig. 4.17 are more sparse since the market shares in this iteration have been constrained to the shares selected in the prior Producer-Consumer iteration.
Fig. 4.19 is similar to Fig. 4.16, and represents the Producer-Consumer pricing and market class share search in a subsequent round of iteration, after the producer has revised the vehicle design options. Unlike the initial iteration, the range of cross-subsidy pricing flexibility is now sufficient to allow the convergence criteria to be met, as shown in the lower left and lower right panels.
4.6. Effects Module
In its primary function as a regulatory support tool, OMEGA’s modeled outputs are intended to inform the type of benefit-cost analyses used in EPA rulemakings and other analyses. We would likely use many of OMEGA’s outputs directly in the analysis for a regulatory action. In other cases, OMEGA produces values that might help inform other models like MOVES. The scope of OMEGA’s effects modeling includes estimating both monetized or cost effects and physical effects. The Effects Module builds on the outputs of the Consumer and Producer modules along with the analysis context inputs as shown in Fig. 4.20.
- Key examples of physical effects that OMEGA will estimate:
Stock of registered vehicles, along with key attributes
VMT of registered vehicles
Tailpipe GHG and criteria pollutant emissions
Upstream (refinery, power sector) GHG and criteria pollutant emissions
- Key examples of monetized effects that OMEGA will estimate:
Vehicle production costs
Vehicle ownership and operation costs, including fuel and maintenance
Other consumer effects
Impacts of criteria air pollutants
Impacts of greenhouse gas pollutants
Congestion, noise, and safety costs
The Effects Module generates: physical effects, cost effects, safety effects, benefits and social effects. In general, the cost effects and benefits output files build upon the physical effects output file in conjunction with several of the context input files. Those context input files are the cost factors, vehicle emission rate inputs and upstream emission source data files. For example, the benefits file would present CO2-related benefits as the CO2 cost factor (a social cost of GHG per metric ton value set in the input file) multiplied by the emission impacts of CO2 (or other GHG) calculated using physical effects. Similarly, fuel costs would be calculated as fuel prices (dollars/gallon as provided in the input file) multiplied by gallons consumed as presented in the physical effects file.
One attribute appears in both the cost effects and the benefits files. That attribute is the drive value which is the economic value of the increased owner/operator surplus provided by added driving and is estimated as one half of the product of the decline in vehicle operating costs per vehicle-mile and the resulting increase in the annual number of miles driven via the rebound effect, plus the cost of driving those rebound miles. Since the drive value is calculated using a change in operating costs, the new operating costs must be compared to another operating cost. Drive value is calculated as a cost and presented in the cost effects file as the drive surplus plus the fuel costs associated with driving any rebound miles. Drive value is then calculated as a benefit by calculating the drive value cost in an action scenario relative to the no-action scenario. If the drive value cost is greater in the action scenario, a positive drive value benefit will be the result while a lower drive value cost in the action scenario would represent a negative benefit, or disbenefit.
Importantly, the cost factor inputs (as OMEGA calls them) have been generated using several discount rates. The values calculated using each of the different discount rates should not be added to one another. In other words, PM costs calculated using a 3 percent discount rate and a 7 percent discount rate should never be added together. Similarly, climate costs calculated using a 3 percent discount rate and a 2.5 percent discount rate should never be added. This does not necessarily hold true when adding criteria air pollutant costs and climate costs when it is acceptable to add costs using different discount rates. Lastly, when discounting future values, the same discount rate must be used as was used in generating the cost factors.
The default effects files are annual summary results by calendar year, regulatory class and fuel type. If desired, vehicle-level output files can be selected via the RUNTIME OPTIONS portion of the effects batch file. The vehicle-level output files can be very large depending on the number of vehicles, length of vehicle life and number of calendar years included in the run. Files can be saved in a compressed ‘parquet’ format for use with Python’s pandas library to minimize file sizes, however, the parquet format is available only when running via OMEGA code and not when running via an executable bundle.
Note that the effects module is a separate runtime process from the producer and consumer processes discussed above. The effects module can be run from code by running omega_effects_main.py or by running the exectuable file. Either way, the user will be prompted to select the desired batch file for the run.
4.6.1. Physical Effects Calculations
Physical effects are calculated at the vehicle level for all calendar years included in the analysis. Vehicle_ID and VMT driven by the given vehicle are pulled from the VehicleAnnualData class. Vehicle attributes are pulled from Vehicle class. Fuel attributes are pulled from the OnroadFuel class which draws them from the onroad_fuels input file.
4.6.2. Fuel Consumption
Liquid fuel consumption and electricity consumption are calculated for a given Vehicle ID as:
Liquid fuel consumption
(4.4)
Where:
is calculated within OMEGA and accounts for any credits that do not improve fuel consumption and test-to-onroad gaps
is the content of the in-use, or retail, fuel
Electricity consumption
(4.5)
Where:
is calculated within OMEGA and accounts for any credits that do not improve fuel consumption and test-to-onroad gaps
is the efficiency of the energy transfer from the charge point to the battery as set by the user
Note
Multi-fuel vehicle fuel consumption
Multi-fuel vehicles consume both electricity and liquid fuel. Consumption of both is calculated for such vehicles and emission effects such as upstream and vehicle emissions are calculated uniquely for both fuels.
4.6.3. Emission Inventories
Emission inventories are calculated for a given Vehicle ID as:
Vehicle Exhaust Criteria Emissions (except for SO2)
(4.6)
Where:
would be any of the criteria air pollutants such as VOC, PM2.5, NOx, etc., with the exception of
(which is calculated interanlly in OMEGA)
is an emission rate from the vehicle emission rates input file
= 907,185
Vehicle Exhaust SO2
(4.7)
Where:
is calculated by equation (4.4)
is the emission rate from the emission rates input file
= 907,185
Vehicle Exhaust CH4 and N2O Emissions
(4.8)
Where:
would be either or
is an emission rate from the emission rates input file
= 1,000,000
Vehicle Exhaust CO2 Emissions
(4.9)
Where:
is calculated within OMEGA and accounts for any credits that do not improve fuel consumption and test-to-onroad gaps
= 1,000,000
Vehicle Brake Wear Criteria Emissions
(4.10)
Where:
would be any of the criteria air pollutants such as VOC, PM2.5, NOx, etc.
is an emission rate from the vehicle emission rates input file
= 907,185
Vehicle Tire Wear Criteria Emissions
(4.11)
Where:
would be any of the criteria air pollutants such as VOC, PM2.5, NOx, etc.
is an emission rate from the vehicle emission rates input file
= 907,185
Vehicle Evaporative Criteria Emissions
(4.12)
Where:
is calculated by equation (4.4)
is the emission rate from the emission rates input file
= 907,185
Upstream Criteria Emissions
(4.13)
Where:
would be any of the criteria air pollutants such as VOC, PM2.5, NOx, etc.
is calculated by equation (4.5)
is the Electricity Generating Unit (or Power Sector) emission factor for the given Pollutant
is calculated by equation (4.4)
is the Refinery emission rate for the given pollutant
= 907,185
Upstream GHG Emissions
(4.14)
Where:
would be any of the GHGs such as CO2, CH4, N2O
is calculated by equation (4.5) divided by the grid transmission efficiency as set by the user
is the Electricity Generating Unit (or Power Sector) emission factor for the given Pollutant
is calculated by equation (4.4)
is the Refinery emission rate for the given pollutant
= 1,000,000
Total Criteria Emissions
(4.15)
Where:
is calculated by the applicable exhaust emission equation
is calculated by (4.10)
is calculated by (4.11)
is calculated by (4.12)
(4.16)
Where:
Total GHG Emissions
(4.17)
Where:
4.6.4. Cost Effects Calculations
Cost effects are calculated at the vehicle level for all calendar years included in the analysis and for, primarily, the physical effects described above.
4.6.5. Benefits Calculations
Benefits are calculated at the fleet level by calendar year and are calculated based on the changes in physical effects relative to the no-action scenario specified in the batch settings input file for the effects run.
5. User Guide
5.1. OMEGA Model
The primary input to OMEGA is the batch definition file which contains rows for each user input required to define a simulation session or group of sessions.
The line-by-line documentation of the batch definition file is available at omega_model/omega_batch.py
and won’t be repeated here.
Batch definition inputs can be scalar values or input file paths (relative to the location of the batch file and/or absolute).
Several of the input files may dynamically load user-definable modules at runtime. These files are indicated as user_definable
in the table below. User-definable inputs and modules are loaded by interpreting the input file input_template_name:
field. For example, if the input template name of a user-definable input is consumer.market_classes
then the Python module omega_model/consumer/market_classes.py
will be used to load the rest of the input file, which may contain an arbitrary format known to the module. The process of creating user-definable modules is a topic for developers.
Below is a table with links to the modules that load the files and their documentation of the input file formats.
- Batch Input Files and Loaders
Parameter
Loaded By
Context Fuel Prices File
Context Electricity Prices File
user_definable
e.g.omega_model/context/fuel_prices.py
Context New Vehicle Market File
Manufacturers File
Market Classes File
user_definable
e.g.omega_model/consumer/market_classes_ice_bev_phev_body_style.py
Onroad Fuels File
Onroad Vehicle Calculations File
Onroad VMT File
user_definable
e.g.omega_model/consumer/annual_vmt_fixed_by_age.py
Producer Generalized Cost File
user_definable
e.g.omega_model/producer/producer_generalized_cost.py
Production Constraints File
Sales Share File
user_definable
e.g.omega_model/consumer/sales_share_ice_bev_phev_body_style.py
Vehicle Price Modifications File
Vehicle Reregistration File
user_definable
e.g.omega_model/consumer/reregistration_fixed_by_age.py
ICE Vehicle Simulation Results File
user_definable
e.g.omega_model/context/rse_cost_clouds.py
BEV Vehicle Simulation Results File
user_definable
e.g.omega_model/context/rse_cost_clouds.py
PHEV Vehicle Simulation Results File
user_definable
e.g.omega_model/context/rse_cost_clouds.py
Vehicles File
Powertrain Cost File
user_definable
e.g.omega_model/context/powertrain_cost_frm.py
Glider Cost File
Body Styles File
Mass Scaling File
Workfactor Definition File
Session Policy Alternatives Settings
Drive Cycle Weights File
Drive Cycle Ballast File
Drive Cycles File
GHG Credit Params File
GHG Credits File
GHG Standards File
user_definable
e.g.omega_model/policy/targets_footprint.py
Off-Cycle Credits File
user_definable
e.g.omega_model/policy/offcycle_credits.py
Policy Fuel Upstream Methods File
Policy Fuels File
Production Multipliers File
Regulatory Classes File
user_definable
e.g.omega_model/policy/regulatory_classes.py
Required Sales Share File
Policy Utility Factor Methods File
- Simulation Context
The context inputs apply to all sessions within a batch. Multiple batch files must be defined to run multiple contexts.
- Simulation Sessions
- The Context Session
The batch file must define at least one simulation session, known as the context session, which is the left-most session in the batch definition file. The context session should align with the provided context inputs. For example, if the context fuel price and new vehicle market data are from AEO, then the policy inputs of the reference session must be consistent with the assumptions used by AEO to generate the projections. For example, the sales projections take into account ghg and fuel economy policies in force or projected at the time and the policy inputs used for the context session should be consistent with those. It would be inconsistent to assume the same sales for a different ghg/fuel economy policy.
- Policy Alternative Sessions
Optionally, one or more alternative policy sessions may be defined in subsequent columns. Typically these would be various policies under evaluation via OMEGA or perhaps a single policy with various alternative inputs or assumptions.
- OMEGA Batch Command Line Interface
The batch process can be initiated from the OMEGA GUI or from the command line by running
omega_batch.py
directly, as in:
>>python omega_model/omega_batch.py --bundle_path path/to/my/bundle_folder --batch_file path/to/my/batch_file.csv
or
>>python omega_model/omega_batch.py --bundle_path path/to/my/bundle_folder --ui_batch_file
In fact, the GUI can be thought of as a wrapper to a command line call to omega_batch.py
. The paths supplied to the GUI fill in the --bundle_path
and --batch_file
arguments.
Typical Command Line Usage (not all available command-line options shown)
usage: omega_batch.py
[-h] [--bundle_path BUNDLE_PATH] [--batch_file BATCH_FILE] [--ui_batch_file]
[--session_num SESSION_NUM] [--analysis_final_year ANALYSIS_FINAL_YEAR]
[--verbose] [--show_figures]
Run OMEGA batch simulation
optional arguments:
-h, --help show this help message and exit
--bundle_path BUNDLE_PATH
Path to bundle folder
--batch_file BATCH_FILE
Path to batch definition file
--ui_batch_file
Select batch file from dialog box
--session_num SESSION_NUM
ID # of session to run from batch
--analysis_final_year ANALYSIS_FINAL_YEAR
Override analysis final year
--verbose Enable verbose omega_batch messages
Other command line arguments are available, mostly associated with parallel processing options and implementation or code development. The full list of arguments can be viewed as follows:
>>python omega_model/omega_batch.py
or
>>python omega_model/omega_batch.py -h
or
>>python omega_model/omega_batch.py --help
- Selecting Sessions to Run
Sessions can be enabled or disabled within the batch file by setting the
Enable Session
field toTRUE
orFALSE
, respectively. Alternatively, the--session_num
argument can be passed toomega_batch
. The reference session is session number0
. The reference session cannot be disabled, regardless of theEnable Session
field value, as it generates reference vehicle prices that the other sessions require in order to calculate overall vehicle sales.- Understanding the Batch Process
The first step in the batch process is to copy the complete source code to the
bundle
folder (in theomega_model
directory, or as specified by the user via the--bundle_path
argument) and to create subfolders for each active session. Within each session folder will be anin
folder (and anout
folder will be created when the session runs). The bundle folder contains the original batch definition file as well as a timestamped batch definition file that is actually run. The timestamped file has the original batch settings with new session input file paths relative to the bundle. The bundle folder contains arequirements.txt
file for reference. When running from source code the requirements file indicates the version of Python used to run the batch and contains the list of installed Python packages and their versions at the time, e.g.python_3_8_10_requirements.txt
. When running from the executable the contents of theGUI_requirements.txt
file indicates the version number of the GUI.The batch itself and each session will have a log file indicating the progress and success or failure of the process. The batch log file is named
batch_logfile.txt
and exists at the top of the bundle folder. Session logs have the prefixo2log_
and are located in each session’sout
folder.If a session completes successfully, the session folder is renamed and prepended with an underscore,
_
. Failed session folders are prepended with#FAIL_
. In this way the session status can be monitored by observing the folder names as the batch runs.Since the bundle folder contains the source code and all inputs for every session it is possible to re-run a batch, or part of a batch, at a later time and reproduce the results if desired. To do so, remove any session folder prefixes and use
omega_batch.py
to re-run the timestamped batch file, while supplying the--no_bundle
and--no_validate
arguments, since the batch has already been bundled. As in:
>>python path/to/my/bundle_folder/omega_model/omega_batch.py --batch_file path/to/my/bundle_folder/YYYY_MM_DD_hh_mm_ss_batch.csv --no_bundle --no_validate
5.2. OMEGA Effects
The primary inputs to the OMEGA effects calculator are the OMEGA Model’s vehicles and vehicle annual data output files for sessions of interest. For the Effects calculator to find these necessary OMEGA Model output files, the user must provide to the Effects calculator the path where they can be found. This is done via the effects batch input file. Assuming the user has run the OMEGA Model and has the bundled results saved to an accessible directory, then the effects batch input file should provide the full system path to that directory.
Importantly, the effects batch input file must also provide a session name associated with each session for which effects are to be calculated. The session name must be consistent with the session name used in the OMEGA Model run. These session names also need to include a context session name, a no action session name and at least one action session name. These are needed to calculate the effects properly since the context session serves to calculate fleet vehicle miles traveled (VMT) and fleet fuel costs per mile from which any VMT rebound effects in subsequent sessions can be calculated.
The OMEGA effects calculator will look for several necessary files within the “in” folder of the context session folder contained within the bundled OMEGA Model results (i.e., the user need not specify these files in the effects batch input file). In addition to the context session, a no action and action session are required because some of the effects calculations are meant to calculate impacts of a policy action relative to a no action, or business as usual, policy. In particular, the benefits calculations can only be done by first calculating physical effects of the action policy relative to the no action policy since benefits do not exist, within OMEGA, absent a policy change.
The other inputs to the OMEGA effects calculator are those associated with: vehicle emission rates; EGU and refinery data; cost factors associated with criteria air pollutants, GHG emissions, energy security impacts, crashes, congestion, noise, vehicle repair, vehicle maintenance, fuel prices, etc. All of these input files must be provided by the user via the effects batch input file.
Below is a table describing the entries needed in the effects batch input file. User entries are to be made in the
value
or full_path
columns of the effects batch input file.
- Batch Input Files and Loaders
parameter
session_policy
description
RUNTIME OPTIONS
Run ID
all
enter
value
for the run identifier for your output folder name or blank for default (default is omega_effects)Run Description
optional only to help the user identify the purpose of the run
Save Path
all
enter
full path
of the folder to which to save results but do not include unique run identifiersSave Input Files
all
enter
value
as True to save input files to your results folder or False to save space and not do soSave Context Fuel Cost per Mile File
all
enter
value
as True or False and note that these files can be large especially in CSV formatSave Vehicle-Level Safety Effects Files
all
enter
value
as True or False and note that these files can be large especially in CSV formatSave Vehicle-Level Physical Effects Files
all
enter
value
as True or False and note that these files can be large especially in CSV formatSave Vehicle-Level Cost Effects Files
all
enter
value
as True or False and note that these files can be large especially in CSV formatFormat for Vehicle-Level Output Files
all
enter
value
as ‘csv’ for large Excel-readable files or ‘parquet’ for compressed files usable in Pandas (value must be csv when running executable)Powertrain Costs FEV
all
enter
value
as True to use FEV developed cost curvesBATCH SETTINGS
batch_folder
all
enter
full_path
of the folder containing OMEGA Model run resultsVehicles File Base Year
all
enter
value
consistent with the OMEGA Model runAnalysis Final Year
all
enter
value
<= the value used in the OMEGA Model runCost Accrual
all
enter
value
as start-of-year or end-of-year - this entry impacts the discounting of costs and benefitsDiscount Values to Year
all
enter
value
to which costs and benefits will be discountedAnalysis Dollar Basis
all
enter
value
consistent with the OMEGA Model runContext Name Liquid Fuel
all
enter
value
of the AEO report (e.g. AEO2021) used in the OMEGA Model runContext Case Liquid Fuel
all
enter
value
of the AEO case (e.g. Reference case) used in the OMEGA Model runElectricity Prices
all
enter
value
to specify which electricity prices to use for No Action and Action session effects (e.g.IPM or AEO)
VMT Rebound Rate ICE
all
enter
value
for ICE rebound (e.g. -0.1)VMT Rebound Rate BEV
all
enter
value
for BEV reboundSC-GHG in Net Benefits
all
enter
value
as ‘global’ or ‘domestic’ or ‘both’ (note that both global and domestic benefits are calculatedif available
this only impacts net benefits)”
Maintenance Costs File
all
enter
full_path
of maintenance costs file in CSV formatRepair Costs File
all
enter
full_path
of repair costs file in CSV formatRefueling Costs File
all
enter
full_path
of refueling costs file in CSV format (i.e. the cost of time spent refueling)General Inputs for Effects File
all
enter
full_path
of general inputs for effects file in CSV formatCriteria Cost Factors File
all
enter
full_path
of criteria air pollutant $/ton factors file in CSV formatSCGHG Cost Factors File
all
enter
full_path
of social cost of GHG $/ton factors file in CSV formatEnergy Security Cost Factors File
all
enter
full_path
of energy security $/barrel file in CSV formatCongestion-Noise Cost Factors File
all
enter
full_path
of crashes & congestion & noise costs file in CSV formatInsurance and Taxes Cost Factors File
all
enter
full_path
of insurance and taxes cost file in CSV formatLegacy Fleet File
all
enter
full_path
of legacy fleet file in CSV formatCPI Price Deflators File
all
enter
full_path
of CPI price deflators file in CSV formatEGU Data File
all
enter
full_path
of EGU data file in CSV formatRefinery Data File
all
enter
full_path
of Refinery data file in CSV formatSafety Values File
all
enter
full_path
of safety values file in CSV formatFatality Rates File
all
enter
full_path
of fatality rates file in CSV formatSESSION SETTINGS
Session Name
context
enter
value
of the context session nameContext Stock and VMT File
context
enter
full_path
of stock and VMT file file in CSV formatContext Electricity Prices
context
enter
full_path
of electricity prices file used for the context sessionSession Name
no_action
enter
value
of the No Action session nameSession Vehicle Emission Rates File
no_action
enter
full_path
of vehicle emission rates file in CSV format used for the No Action sessionContext Electricity Prices
no_action
enter
full_path
of electricity prices file in CSV format used for the No Action sessionSession Name
action_1
enter
value
of the Action session nameSession Vehicle Emission Rates File
action_1
enter
full_path
of vehicle emission rates file in CSV format used for the Action sessionContext Electricity Prices
action_1
enter
full_path
of electricity prices file in CSV format used for the Action session
5.2.1. Runtime Options
The effects results will be saved to a folder specified in the save_path full_path
entry (e.g. “c:/omega/effects”). In that save_path folder,
a folder will be auto generated and will have the same name as the OMEGA Model batch for which effects are being calculated.
Within that batch folder, a run results folder will be auto generated whose name will consist of a date and timestamp associated with
the time of the OMEGA effects calculator run along with the run ID to assist in keeping track of different runs and ensuring that nothing is
overwritten by future runs. As a result, you might find your results saved to a folder named something like
“c:/omega/effects/ld_omega_model_batch/20230504_090000_omega_effects” for a run done on May 4, 2023, at 9:00AM.
Note that some effects output files may or may not be desired. The effects are calculated for every vehicle in the fleet in every
year up to and including the Analysis Final Year value
. If you run through 2055, this becomes a large number of vehicles and
the vehicle-level output files can become very large (0.5 GB to 1 GB per file). Depending on your machine, you may have trouble
viewing those files let alone conducting analyses of the results (e.g., in Excel or OpenOffice). Saving of these large output files
can be avoided by setting the “Save Vehicle-Level” file value
to False. Alternatively, the user can generate those files in
parquet format, which is a compressed file format, to save space. Parquet files are readable by Python’s Pandas library but cannot
be opened directly in a spreadsheet application. Instructions for reading saved parquet files in Pandas are included in the save_file function
of /omega_effects/general/file_id_and_save.py
. Note that saving to parquet format only works
when running from the OMEGA code, and that the selection must be set to ‘csv’ format when running from the executable.
5.2.2. Batch Settings
The files specified in the Batch Settings section of the effects batch input file are meant to apply to all sessions in the batch.
5.2.3. Session Settings
Any session can be run in the OMEGA Effects calculator provided those sessions exist in the batch_folder. A value
for
the session name must be provided. A session can be ignored by setting the Session Name value
to None. A Context Session Name
must be provided and no session meant to be included can have a session name of None.
5.2.4. Emission Rates Files
Note that an action session may require a different emission rate input file than that used for the no action session for, say, vehicle emission rates in the event that the policy impacts vehicle emission rates.
5.2.5. Running the OMEGA Effects Executable
The OMEGA Effects code, input files and output files can be found on the OMEGA webpage at this link https://www.epa.gov/regulations-emissions-vehicles-and-engines/optimization-model-reducing-emissions-greenhouse-gases
The OMEGA Effects are not part of the OMEGA Model executable file. The OMEGA Effects can be run using the Python code included in the OMEGA repository at https://github.com/USEPA/EPA_OMEGA_Model or the Python code included in the zip file available at the OMEGA webpage linked above.
Alternatively, the OMEGA Effects can be run using a separate executable file available on the OMEGA webpage (recommended).
These instructions assume that the executable file is being used to generate the OMEGA Effects.
Place the executable file in your preferred location on your local machine.
Place the inputs files in your preferred location on your local machine.
Find a copy of the effects batch settings file.
In cell C3 of the batch settings file, enter a run ID if desired (e.g., My_run, test, etc.). This run ID will be included as part of the output folder name. The default value is omega_effects.
In cell D5, enter the path of the save folder (e.g., “C:/omega/effects”). The output folder will be saved to this folder. The output folder will be named using other entries in the batch file and the run ID set in step 8.
Other options in Column C can be set to TRUE or FALSE, but please read the notes associated with each.
In cell D14 of the batch settings file, enter the full path to the folder that contains your OMEGA compliance run results. This is important since the OMEGA Effects will look to this folder to find the needed vehicles.csv and vehicle_annual_data.csv files generated for each session in your OMEGA compliance run.
Most values in column C can be left as is. There must be a context session name in cell C42. If your context session name is different, then set cell C42 accordingly. The same is true of subsequent session names in column C. If you do not want your effects outputs to include a session that exists in your OMEGA compliance run folder, simply set the session name to None.
Remaining entries in Column D should then point to the inputs folder on your local machine. Filenames can probably be left as is unless you are using files with different names.
After setting up the batch settings file, be sure to save it as a CSV file (not Excel).
Double click the executable file.
The executable should launch. Be patient. After several seconds, a file dialog window should open asking for the batch settings file. Navigate to the batch settings file you saved in step 14, select it, and click open. The executable should now run using the settings in your batch settings file.
6. Developer Guide
This Developer Guide will assist those interested in the latest (pre-release) version of OMEGA available from source code. This guide assumes some familiarity with Python programming and development, but also attempts to point newcomers in the right direction where possible.
6.1. Github Repository
The development version of OMEGA is available in the developer
branch of the EPA_OMEGA_Model GitHub repository:
https://github.com/USEPA/EPA_OMEGA_Model
The developer
branch contains in-development, pre-release code, subject to change without notice and no guarantees as to stability at any given point in time. Features may be added or removed and may or may not be used for future rulemakings.
Releases will be available on separate branches that contain only the particular release in question.
The developer
branch can be accessed via .zip
file directly (https://github.com/USEPA/EPA_OMEGA_Model/archive/refs/heads/developer.zip), via GitHub-integrated development environments or via GitHub command-line calls (e.g. gh repo clone USEPA/EPA_OMEGA_Model
).
The OMEGA development team uses PyCharm Community Edition to write and debug code, but any Python development environment may be used.
6.2. Setup
After downloading the source code (via .zip
file or cloning the repository), it is necessary to install Python and various required Python packages.
6.2.1. Python
The latest versions of Python are available at https://www.python.org/downloads/
OMEGA has been developed with Python versions 3.7.1 (the minimum required version) thru 3.11.6 and has not been tested with version 3.12 or higher. If you already have Python installed, there is probably no reason to update to a newer version unless one of the required packages is not compatible with your Python version and hardware platform.
The recommended practice is to run the source code in a virtual environment, which may be set up manually or via the IDE. The virtual environment isolates the installation of OMEGA-required Python packages from whatever packages may have already been installed at the system level. This allows a ‘clean’ installation that can guarantee no known conflicts between packages.
6.2.2. Required Packages
In addition to Python, OMEGA requires several publicly available Python packages in order to run. These are detailed in the requirements.txt
file.
6.2.2.1. Simple Install
The simplest way to install the packages is to use pip
, the package installer for Python. Sometimes there is an updated version of pip
available. The command-line code below updates pip
and installs the packages detailed in requirements.txt
.
python -m pip install --upgrade pip setuptools
pip install -r requirements.txt
6.2.3. Running From Source Code
There are at least four common ways to run OMEGA:
from the executable GUI (see Getting Started and Running OMEGA using the Graphical User Interface (GUI))
from source at the command line as a single (default) session via
omega_model.omega
from source at the command line as a GUI via
omega_gui.omega_gui
from source at the command line as a batch via
omega_model.omega_batch
(See also OMEGA Batch Command Line Interface)
To run the default session directly from source at the command line from the project top-level folder:
python omega_model/omega.py
Will produce output such as:
loading omega version X.Y.Z
importing XXX.py
...
Initializing OMEGA Quick Test:
importing XYZ.py
...
Running OMEGA Quick Test:
Running OMEGA Quick Test Pass 0: Manufacturer=consolidated_OEM
Running OMEGA Quick Test: Year=2020 Iteration=0 consolidated_OEM
Running OMEGA Quick Test: Year=2020 Iteration=1 consolidated_OEM
Running OMEGA Quick Test: Year=2020 Iteration=2 consolidated_OEM
Running OMEGA Quick Test: Year=2021 Iteration=0 consolidated_OEM
Running OMEGA Quick Test: Year=2021 Iteration=1 consolidated_OEM
Running OMEGA Quick Test: Year=2021 Iteration=2 consolidated_OEM
Session ended at 2023-04-05 11:38:00
Session elapsed time 120.56 seconds
The primary use case for running omega.py
directly is just to confirm the installation or perhaps when it’s simpler to debug code without the overhead of the batch process.
To run the gui directly from source at the command line from the project top-level folder:
python omega_gui/omega_gui.py
For all other development use cases it is recommended to run omega_batch.py
as shown in the User Guide under OMEGA Batch Command Line Interface
7. Code Details
7.1. omega_effects package
OMEGA effects post-processing subpackage.
CODE
7.1.1. Subpackages
7.1.1.1. omega_effects.consumer package
OMEGA effects code consumer subpackage.
CODE
7.1.1.1.1. Submodules
7.1.1.1.2. omega_effects.consumer.annual_vmt_fixed_by_age module
Routines to load and provide access to annual vehicle miles travelled (VMT) by market class and age.
The data represents a fixed VMT schedule by age.
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows. The template header uses a dynamic format.
The data represents the re-registered proportion of vehicles by calendar year, age and market class.
- File Type
comma-separated values (CSV)
- Template Header
input_template_name:
[module_name]
input_template_version:
[template_version]
- Sample Header
input_template_name:
consumer.annual_vmt_fixed_by_age
input_template_version:
0.2
- Sample Data Columns
start_year
age
market_class_id
annual_vmt
2019
0
non_hauling.BEV
14699.55515
2019
1
non_hauling.BEV
14251.70373
2019
2
non_hauling.BEV
14025.35397
2019
0
hauling.ICE
15973.88982
2019
1
hauling.ICE
15404.1216
2019
2
hauling.ICE
14840.93011
- start_year:
Start year of annual VMT data, values apply until the next available start year
- age:
Vehicle age, in years
- market_class_id:
Vehicle market class ID, e.g. ‘hauling.ICE’
- annual_vmt:
Vehicle miles travelled per year at the given age for the given market class ID
CODE
- class OnroadVMT
Bases:
object
Loads and provides access to annual Vehicle Miles Travelled by calendar year, market class, and age.
- __init__()
- init_from_file(filepath, effects_log)
Initialize class data from input file.
- Parameters:
filepath – the Path object to the file.
effects_log – an instance of the EffectsLog class.
- Returns:
Nothing, but reads the appropriate input file.
- get_vmt(calendar_year, market_class_id, age)
Get vehicle miles travelled by calendar year, market class and age.
- Parameters:
calendar_year (int) – calendar year of the VMT data
market_class_id (str) – market class id, e.g. ‘hauling.ICE’
age (int) – vehicle age in years
- Returns:
(float) Annual vehicle miles travelled.
- get_cumulative_vmt(market_class_id, age)
Get cumulative VMT for the given market class id and age.
- Parameters:
market_class_id (str) – market class id, e.g. ‘hauling.ICE’
age (int) – vehicle age in years
- Returns:
Cumulative VMT for the given market class id and age.
7.1.1.1.3. omega_effects.consumer.cost_factors_insurance_and_taxes module
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
cost_factors_insurance_and_taxes
input_template_version:
0.2
- Sample Data Columns
powertrain_type
body_style
item
value
dollar_basis
notes
all
all
averge_state_taxes
0.0502
all
sedan
average_insurance_cost
(vehicle_value * 0.009 + 220) * 1.19
2019
all
cuv_suv
average_insurance_cost
(vehicle_value * 0.005 + 240) * 1.19
2019
ICE
all
average_depreciation_rate
0.149
HEV
all
average_depreciation_rate
0.149
Data Column Name and Description
- powertrain_type:
E.g., BEV, ICE, HEV, PHEV
- body_style:
E.g., sedan, cuv_suv, pickup
- item:
The attribute name.
- value:
The attribute value associated with the paired attribute name.
- dollar_basis:
The dollar basis, if applicable, for the paired attribute value.
- notes:
User supplied notes ignored in code.
CODE
- class InsuranceAndTaxes
Bases:
object
Loads and provides access to insurance and tax cost factors by calendar year.
- __init__()
- init_from_file(filepath, batch_settings, effects_log)
Initialize class data from input file.
- Parameters:
filepath – the Path object to the file.
batch_settings – an instance of the BatchSettings class.
effects_log – an instance of the EffectsLog class.
- Returns:
Nothing, but reads the appropriate input file.
- get_attribute_value(powertrain_type, body_style, *attribute_names)
Get cost factors
- Parameters:
powertrain_type (str) – e.g., ‘BEV’, ‘ICE’, ‘HEV’, ‘PHEV’
body_style (str) – e.g., ‘sedan’, ‘cuv_suv’, ‘pickup’
attribute_names (str) – the attribute name(s) for which a value is sought
- Returns:
Cost factor or list of cost factors
- get_tax_rate(attribute_name)
- Parameters:
attribute_name (str) – the attribute name for which a value is sought
- Returns:
The tax rate value for the passed attribute_name
- calc_insurance_cost(avg_purchase_price, powertrain_type, body_style, age)
- Parameters:
avg_purchase_price (float) – the average purchase price of the vehicle
powertrain_type (str) – e.g., ‘BEV’, ‘ICE’, ‘HEV’, ‘PHEV’
body_style (str) – e.g., ‘sedan’, ‘cuv_suv’, ‘pickup’
age (int) – the age of the vehicle
- Returns:
The cost of insurance taking into consideration depreciation of the vehicle’s value
7.1.1.1.4. omega_effects.consumer.deregionalizer module
OMEGA effects code de-regionalizer module.
Used with ‘zev’ and ‘nonzev’ market classes.
CODE
- remove_region_entries(df, attribute, attribute_values_to_remove, string_for_removal, *args)
- Parameters:
df (DataFrame) – DataFrame containing region specific values to be removed.
attribute (str) – the attribute to act on (e.g., ‘market_class_id’, ‘body_style’).
attribute_values_to_remove (str) – the string to search on to remove entries (e.g., ‘r1nonzev’, ‘r2zev’).
string_for_removal (str) – the string to replace while keeping entries (e.g., ‘r1nonzev’, ‘r2zev’).
args (str or strs) – the attribute values to be deregionalized.
- Returns:
A new DataFrame with region specific data removed.
- deregionalize_entries(df, attribute, *args)
- Parameters:
df (DataFrame) – DataFrame containing region specific values to be deregionalized.
attribute (str) – the attribute to act on (e.g., ‘market_class_id’, ‘body_style’).
args (str or strs) – the strings to remove from entries.
- Returns:
A new DataFrame with region specific data removed.
- clean_body_styles(df)
- Parameters:
df (DataFrame) – DataFrame containing body_style entries to be made consistent.
- Returns:
DataFrame with body_styles consistent with effects inputs.
7.1.1.1.5. omega_effects.consumer.reregistration_fixed_by_age module
Vehicle re-registration, fixed by age.
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows. The template header uses a dynamic format.
The data represents the re-registered proportion of vehicles by model year, age and market class.
- File Type
comma-separated values (CSV)
- Template Header
input_template_name:
[module_name]
input_template_version:
[template_version]
- Sample Header
input_template_name:
consumer.reregistration_fixed_by_age
input_template_version:
0.2
- Sample Data Columns
start_model_year
age
market_class_id
reregistered_proportion
1970
0
non_hauling.BEV
1
1970
1
non_hauling.BEV
0.987841531
1970
2
non_hauling.BEV
0.976587217
1970
0
hauling.ICE
1
1970
1
hauling.ICE
0.977597055
1970
2
hauling.ICE
0.962974697
Data Column Name and Description
- start_model_year:
The start vehicle model year of the re-registration data, values apply until next available start year
- age:
Vehicle age, in years
- market_class_id:
Vehicle market class ID, e.g. ‘hauling.ICE’
- reregistered_proportion:
The fraction of vehicles re-registered, [0..1]
CODE
- class Reregistration
Bases:
object
Load and provide access to vehicle re-registration data by model year, market class ID and age.
- __init__()
- init_from_file(filepath, effects_log)
Initialize class data from input file.
- Parameters:
filepath – the Path object to the file.
effects_log – an instance of the EffectsLog class.
- Returns:
Nothing, but reads the appropriate input file.
- get_reregistered_proportion(model_year, market_class_id, age)
Get vehicle re-registered proportion [0..1] by market class and age.
- Parameters:
model_year (int) – the model year of the re-registration data
market_class_id (str) – market class id, e.g. ‘hauling.ICE’
age (int) – vehicle age in years
- Returns:
Re-registered proportion [0..1]
7.1.1.2. omega_effects.context package
OMEGA effects code context subpackage.
CODE
7.1.1.2.1. Submodules
7.1.1.2.2. omega_effects.context.context_stock_vmt module
Routines to load and access stock vmt from the analysis context
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows.
The data represents stock vmt by context case, case id and calendar year.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
context_stock_vmt
input_template_version:
0.1
- Sample Data Columns
context_id
calendar_year
case_id
miles
stock
AEO2022
2021
Reference case
2.76E+12
260088654
AEO2022
2022
Reference case
2.89E+12
261614075
AEO2022
2023
Reference case
2.99E+12
263155182
AEO2022
2024
Reference case
3.03E+12
264624603
AEO2022
2025
Reference case
3.08E+12
266039459
- Data Column Name and Description
- context_id:
The name of the context source, e.g. ‘AEO2020’, ‘AEO2021’, etc
- case_id:
The name of the case within the context, e.g. ‘Reference Case’, ‘High oil price’, etc
- calendar_year:
The calendar year of the fuel costs
- miles:
The vehicle miles traveled
- stock:
The vehicle stock
CODE
- class ContextStockVMT
Bases:
object
Loads and provides access to stock vmt from the analysis context
- __init__()
- init_from_file(filepath, batch_settings, effects_log)
Initialize class data from input file.
- Parameters:
filepath – the Path object to the file.
batch_settings – an instance of the BatchSettings class.
effects_log – an instance of the EffectsLog class.
- Returns:
Nothing, but reads the appropriate input file.
- get_context_stock_vmt(calendar_year)
- Parameters:
calendar_year (int) – the calendar year for which stock vmt is sought
- Returns:
The stock and vmt values for the passed calendar year
- calc_growth(calendar_year, *args)
- Parameters:
calendar_year (int) – the calendar year for which stock and vmt are sought
args (str or strs) – the attribute(s) for which to calculate growth
- Returns:
The stock and vmt values for the passed calendar year when/if that year is beyond the input max; growth is based on the input data.
7.1.1.2.3. omega_effects.context.cpi_price_deflators module
Routines to load CPI price deflators.
Used to convert monetary general to a consistent dollar basis, e.g., in the cost_factors_criteria
module.
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows.
The data represents the price deflator by calendar year.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
context_cpi_price_deflators
input_template_version:
0.22
- Sample Data Columns
calendar_year
price_deflator
2010
218.056
2011
224.939
Data Column Name and Description
- calendar_year:
Calendar year of the price deflator
- price_deflator:
CPI price deflator
CODE
- class CPIPriceDeflators
Bases:
object
Loads and provides access to CPI price deflators by calendar year.
- __init__()
- init_from_file(filepath, effects_log)
Initialize class data from input file.
- Parameters:
filepath – the Path object to the file.
effects_log – an instance of the EffectsLog class.
- Returns:
Nothing, but reads the appropriate input file.
- get_price_deflator(calendar_year, effects_log)
Get the CPI price deflator for the given calendar year.
- Parameters:
calendar_year (int) – the calendar year to get the function for
effects_log – an instance of the EffectsLog class
- Returns:
The CPI price deflator for the given calendar year.
- adjust_dollars(batch_settings, df, effects_log, *args)
- Parameters:
batch_settings – an instance of the BatchSettings class.
df (DataFrame) – values to be converted to a consistent dollar basis.
effects_log – an instance of the EffectsLog class.
args (str or strs) – The attributes to be converted to a consistent dollar basis.
- Returns:
The passed DataFrame with args expressed in a consistent dollar basis.
7.1.1.2.4. omega_effects.context.electricity_prices module
Routines to load and access electricity prices from the analysis context and the sessions
INPUT FILE FORMAT
The file format consists of a one-row data header and subsequent data rows.
The data represent electricity charging costs per kWh.
- File Type
comma-separated values (CSV)
- Sample Data Columns
context_id
dollar_basis
case_id
fuel_id
calendar_year
retail_dollars_per_unit
pretax_dollars_per_unit
AEO2020
2019
Reference case
US electricity
2019
0.12559407
0.10391058
AEO2020
2019
Reference case
US electricity
2020
0.1239522
0.10212733
- Data Column Name and Description
- context_id:
The name of the context source, e.g. ‘AEO2020’, ‘AEO2021’, ‘IPM’, etc
- dollar_basis:
- The dollar basis of the fuel prices. Note that this dollar basis is converted in-code to ‘analysis_dollar_basis’
using the implicit_price_deflators input file.
- case_id:
The name of the case within the context, e.g. ‘Reference Case’, ‘High oil price’, for AEO; ‘action’ or ‘no_action’ for IPM
- fuel_id:
The name of the vehicle in-use fuel, must be in the table loaded by
class fuels.Fuel
and consistent with the base year vehicles file (columnin_use_fuel_id
) loaded byclass vehicles.VehicleFinal
- calendar_year:
The calendar year of the fuel costs
- retail_dollars_per_unit:
Retail dollars per unit
- pretax_dollars_per_unit:
Pre-tax dollars per unit
CODE
- class ElectricityPrices
Bases:
object
Loads and provides access to fuel prices from the analysis context
- __init__()
- init_from_file(filepath, batch_settings, effects_log, session_settings=None, context=False)
Initialize class data from input file.
- Parameters:
filepath – the Path object to the file.
batch_settings – an instance of the BatchSettings class.
effects_log – an instance of the EffectsLog class.
session_settings – an instance of the SessionSettings class.
context (bool) – whether context electricity prices (True) or session prices (False)
- Returns:
Nothing, but reads the appropriate input file.
- interpolate_values(batch_settings, session_settings, df, args)
- Parameters:
batch_settings – an instance of the BatchSettings class.
session_settings – an instance of the SessionSettings class.
df (DataFrame) – the input data to be interpolated.
args (list) – the arguments to interpolate.
- Returns:
The passed DataFrame with interpolated values to fill in missing data.
- get_fuel_price(calendar_year, *price_types)
Get fuel price data in calendar_year
- Parameters:
calendar_year (numeric) – calendar year for which to get fuel prices.
price_types (str or strs) – the price types sought (e.g., retail, pretax)
- Returns:
Fuel price or list of fuel prices if multiple attributes were requested
7.1.1.2.5. omega_effects.context.fuel_prices module
Routines to load and access liquid fuel prices from the analysis context
Context fuel price data includes retail and pre-tax costs in dollars per unit (e.g. $/gallon)
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows.
The data represents fuel prices by context case, fuel type, and calendar year.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
context_fuel_prices
input_template_version:
0.2
- Sample Data Columns
context_id
dollar_basis
case_id
fuel_id
calendar_year
retail_dollars_per_unit
pretax_dollars_per_unit
AEO2020
2019
Reference case
pump gasoline
2019
2.665601
2.10838
AEO2020
2019
Reference case
US electricity
2019
0.12559407
0.10391058
- Data Column Name and Description
- context_id:
The name of the context source, e.g. ‘AEO2020’, ‘AEO2021’, etc
- dollar_basis:
The dollar basis of the fuel prices in the given AEO version. Note that this dollar basis is converted in-code to ‘analysis_dollar_basis’ using the implicit_price_deflators input file.
- case_id:
The name of the case within the context, e.g. ‘Reference Case’, ‘High oil price’, etc
- fuel_id:
The name of the vehicle in-use fuel, must be in the table loaded by
class fuels.Fuel
and consistent with the base year vehicles file (columnin_use_fuel_id
) loaded byclass vehicles.Vehicle
- calendar_year:
The calendar year of the fuel costs
- retail_dollars_per_unit:
Retail dollars per unit
- pretax_dollars_per_unit:
Pre-tax dollars per unit
CODE
- class FuelPrice
Bases:
object
Loads and provides access to fuel prices from the analysis context
- __init__()
- init_from_file(filepath, batch_settings, effects_log)
Initialize class data from input file.
- Parameters:
filepath – the Path object to the file.
batch_settings – an instance of the BatchSettings class.
effects_log – an instance of the EffectsLog class.
- Returns:
Nothing, but reads the appropriate input file.
- get_fuel_price(calendar_year, fuel_id, *price_types)
Get fuel price data for fuel_id in calendar_year
- Parameters:
calendar_year (numeric) – calendar year for which to get fuel prices.
fuel_id (str) – fuel ID
price_types (str or strs) – ContextFuelPrices attributes to get
- Returns:
Fuel price or list of fuel prices if multiple attributes were requested
7.1.1.2.6. omega_effects.context.ip_deflators module
Routines to load Implicit Price (IP) deflators.
Used to convert monetary general to a consistent dollar basis, e.g., in the cost_factors_congestion_noise
module.
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows.
The data represents the price deflator by calendar year.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
context_implicit_price_deflators
input_template_version:
0.22
- Sample Data Columns
calendar_year
price_deflator
2001
79.783
2002
81.026
Data Column Name and Description
- calendar_year:
Calendar year of the price deflator
- price_deflator:
Implicit price deflator
CODE
- class ImplicitPriceDeflators
Bases:
object
Loads and provides access to implicit price deflators by calendar year.
- __init__()
- init_from_file(filepath, effects_log)
Initialize class data from input file.
- Parameters:
filepath – the Path object to the file.
effects_log – an instance of the EffectsLog class.
- Returns:
Nothing, but reads the appropriate input file.
- get_price_deflator(calendar_year, effects_log)
Get the implicit price deflator for the given calendar year.
- Parameters:
calendar_year (int) – the calendar year to get the function for
effects_log – an instance of the EffectsLog class.
- Returns:
The implicit price deflator for the given calendar year.
- adjust_dollars(batch_settings, df, effects_log, *args)
- Parameters:
batch_settings – an instance of the BatchSettings class.
df (DataFrame) – values to be converted to a consistent dollar basis.
effects_log – an instance of the EffectsLog class.
args (str or strs) – The attributes to be converted to a consistent dollar basis.
- Returns:
The passed DataFrame with args expressed in a consistent dollar basis.
- dollar_adjustment_factor(batch_settings, dollar_basis_input, effects_log)
- Parameters:
batch_settings – an instance of the BatchSettings class.
dollar_basis_input (int) – the dollar basis of the cost to be adjusted.
effects_log – an instance of the EffectsLog class.
- Returns:
The multiplicative factor that can be applied to a cost in dollar_basis_input to express that value in analysis_dollar_basis.
7.1.1.2.7. omega_effects.context.maintenance_cost module
Routines to load Maintenance Cost Inputs.
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows.
The data represent various inputs for use in maintenance cost calculations.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
maintenance_cost
input_template_version:
0.2
- Sample Data Columns
item
miles_per_event_ICE
miles_per_event_HEV
miles_per_event_PHEV
miles_per_event_BEV
dollars_per_event
dollar_basis
Engine Oil
7500
7500
9000
65
2019
Oil Filter
7500
7500
9000
20
2019
Tire Rotation
7500
7500
7500
7500
50
2019
Data Column Name and Description
- item:
The maintenance attribute name.
- miles_per_event_ICE:
The attribute value for ICE vehicles.
- miles_per_event_HEV:
The attribute value for HEVs.
- miles_per_event_PHEV:
The attribute value for PHEVs.
- miles_per_event_BEV:
The attribute value for BEVs.
- dollars_per_event:
The cost in US dollars per maintenance event.
- dollar_basis:
The dollar basis of values within the table. Values are converted in-code to ‘analysis_dollar_basis’ using the implicit_price_deflators input file.
CODE
- class MaintenanceCost
Bases:
object
Loads and provides access to maintenance cost input values for effects calculations.
- __init__()
- init_from_file(filepath, batch_settings, effects_log)
Initialize class data from input file.
- Parameters:
filepath – the Path object to the file.
batch_settings – an instance of the BatchSettings class.
effects_log – an instance of the EffectsLog class.
- Returns:
Nothing, but reads the appropriate input file.
- get_maintenance_cost_curve_coefficients(veh_type)
- Parameters:
veh_type (str) – The type of powertrain in the vehicle, e.g., ‘ICE’, ‘BEV’, ‘HEV’, ‘PHEV’
- Returns:
The maintenance cost curve coefficients for the given veh_type.
- static calc_maintenance_cost_per_mile_curve(input_df)
- Parameters:
input_df (DataFrame) – the maintenance_cost_inputs.csv file with costs updated to analysis_basis_dollars.
- Returns:
- A dictionary of maintenance cost curve coefficients (slope with intercept=0)
having keys of ‘ICE’, ‘HEV’, ‘PHEV’, ‘BEV’.
Notes
Dividing the cumulative_cost by miles gives a constant cost/mile for every mile. However, costs/mile should be lower early and higher later, so this method determines a triangular area that equates to the cumulative cost. With the slope of that triangular area, a cost/mile at any odometer value can be calculated and the cost of maintenance in any year can then be calculated as that cost/mile multiplied by miles driven in that year.
- static calc_maintenance_cost_per_mile(input_dict)
Calc maintenance cost per mile.
- Parameters:
input_dict – Dictionary of the maintenance cost inputs.
- Returns:
The input_dict with the total maintenance cost per mile added; this cost per mile would be a constant for all miles.
Notes
This method is not being used currently in favor of the calc_maintenance_cost_per_mile_curve method within the class.
7.1.1.2.8. omega_effects.context.onroad_fuels module
Routines to load and retrieve onroad (in-use) fuel attribute data
Fuel data includes a name, units (e.g. gallons, kWh), CO2e g/unit, refuel_efficiency and transmission_efficiency.
See also
vehicles
and context_fuel_prices
modules, and consumer
subpackage
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows.
The data represents fuel property data for on-road/in-use purposes.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
onroad-fuels
input_template_version:
0.1
- Sample Data Columns
fuel_id
start_year
unit
direct_co2e_grams_per_unit
refuel_efficiency
transmission_efficiency
pump gasoline
2020
gallon
8887
1
1
US electricity
2020
kWh
0
0.9
0.935
Data Column Name and Description
- fuel_id:
The Fuel ID, as referenced by the
vehicles
andcontext_fuel_prices
modules, andconsumer
subpackage.- start_year:
Start year of fuel properties, properties apply until the next available start year
- unit:
Fuel unit, e.g. ‘gallon’, ‘kWh’
- direct_co2e_grams_per_unit:
CO2e emissions per unit when consumed
- refuel_efficiency:
Refuel efficiency [0..1], e.g. electrical vehicle charging efficiency
- transmission_efficiency:
Fuel transmission efficiency [0..1], e.g. electrical grid efficiency, may also be referred to as “grid loss”
CODE
- class OnroadFuel
Bases:
object
Loads and provides methods to access onroad fuel attribute data.
- __init__()
- init_from_file(filepath, effects_log)
Initialize class data from input file.
- Parameters:
filepath – the Path object to the file.
effects_log – an instance of the EffectsLog class.
- Returns:
Nothing, but reads the appropriate input file.
- get_fuel_attribute(calendar_year, in_use_fuel_id, attribute)
- Parameters:
calendar_year (numeric) – year to get fuel properties in
in_use_fuel_id (str) – e.g. ‘pump gasoline’)
attribute (str) – name of attribute to retrieve
- Returns:
Fuel attribute value for the given year.
Example
carbon_intensity_gasoline = OnroadFuel.get_fuel_attribute(2020, 'pump gasoline', 'direct_co2e_grams_per_unit')
7.1.1.2.9. omega_effects.context.powertrain_cost module
Routines to powertrain cost.
This omega_effects module reads the powertrain cost file used in the compliance run for the given session for the sole purpose of determinining the battery offset. The SessionSettings class searches for the applicable powertrain cost file for the given session so the user need not worry about the powertrain cost file for effects calculations.
CODE
- class PowertrainCost
Bases:
object
Loads and provides access to the battery_offsets set via the applicable powertrain_cost input file.
- __init__()
- init_from_file(batch_settings, filepath, effects_log)
Initialize class data from input file.
- Parameters:
batch_settings – an instance of the BatchSettings class.
filepath – the Path object to the file.
effects_log – an instance of the EffectsLog class.
- Returns:
Nothing, but reads the appropriate input file.
- get_battery_tax_offset(year, battery_kwh, powertrain_type)
Get battery tax offset.
- Parameters:
year (int) – year for which battery tax credit is needed.
battery_kwh (float) – battery pack capacity in kWh
powertrain_type (str) – ‘BEV’ or ‘PHEV’
- Returns:
The battery tax offset (dollars per kWh credit) for the given year.
7.1.1.2.10. omega_effects.context.refueling_cost module
Routines to load Refueling Cost Inputs.
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows.
The data represent various inputs for use in refueling cost calculations.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
refueling_cost
input_template_version:
0.2
- Sample Data Columns
type
item
value
dollar_basis
car
miles_to_mid_trip_charge
7840 + -64.4 * range + 0.18 * range ** 2
truck
miles_to_mid_trip_charge
6290 + -49.9 * range + 0.135 * range ** 2
suv
share_of_miles_charged_mid_trip
0.241 + -0.001 * range + 0.000001 * range ** 2
truck
fixed_refueling_minutes
3.5
Data Column Name and Description
- type:
The vehicle type, e.g. ‘car’, ‘suv’, etc
- item:
The refueling cost curve attribute name
- value:
Scalar value or expression to be evaluated for cost
- dollar_basis:
The dollar basis year for the cost value, e.g.
2020
CODE
- class RefuelingCost
Bases:
object
Loads and provides access to refueling cost input values for refueling cost calculations.
- __init__()
- init_from_file(filepath, batch_settings, effects_log)
Initialize class data from input file.
- Parameters:
filepath – the Path object to the file.
batch_settings – an instance of the BatchSettings class.
effects_log – an instance of the EffectsLog class.
- Returns:
Nothing, but reads the appropriate input file.
- calc_bev_refueling_cost_per_mile(vehicle_type, bev_range)
- Parameters:
vehicle_type (str) – The type of vehicle, e.g., ‘car’, ‘suv’, ‘truck’.
bev_range (int) – The range (miles) of the BEV on a full charge.
- Returns:
The refueling cost per mile for the given veh_type.
- calc_liquid_refueling_cost_per_gallon(vehicle_type)
- Parameters:
vehicle_type (str) – The type of vehicle, e.g., ‘car’, ‘suv’, ‘truck’.
- Returns:
The refueling cost per mile for the given veh_type.
7.1.1.2.11. omega_effects.context.repair_cost module
Routines to load Repair Cost Inputs.
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows.
The data represent various inputs for use in repair cost calculations.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
repair_cost
input_template_version:
0.1
- Sample Data Columns
item
value
car_multiplier
1
suv_multiplier
0.91
truck_multiplier
0.7
ICE_multiplier
1
HEV_multiplier
0.91
Data Column Name and Description
- item:
The repair cost curve attribute name.
- value:
The attribute value.
CODE
- class RepairCost
Bases:
object
Loads and provides access to repair cost input values for repair cost calculations.
- __init__()
- init_from_file(filepath, effects_log)
Initialize class data from input file.
- Parameters:
filepath – the Path object to the file.
effects_log – an instance of the EffectsLog class.
- Returns:
Nothing, but reads the appropriate input file.
- calc_repair_cost_per_mile(veh_cost, pt_type, repair_type, age)
- Parameters:
veh_cost – (Numeric) The value of the vehicle when sold as new
pt_type – (str) The powertrain type (ICE, HEV, PHEV, BEV)
repair_type – (str) The vehicle repair type (car, suv, truck)
age – (int) The age of the vehicle where age=0 is year 1 in operation
- Returns:
A single repair cost per mile for the given vehicle at the given age
Note
The source data included MSRP up to $100,000 and through 10 years of service; MSRP is limited here to $100,000 but calculations continue beyond 10 years at the growth indicated by the source data.
7.1.1.3. omega_effects.effects package
OMEGA effects main subpackage.
CODE
7.1.1.3.1. Submodules
7.1.1.3.2. omega_effects.effects.benefits module
OMEGA effects benefits module.
CODE
- get_cap_cf(batch_settings, calendar_year, source_id)
Get criteria cost factors
- Parameters:
batch_settings – an instance of the BatchSettings class.
calendar_year (int) – The calendar year for which criteria cost factors are needed.
source_id (str) – the pollutant source, e.g., ‘car pump gasoline’, ‘egu’, ‘refinery’
- Returns:
A list of cost factors as specified in the cost_factors list for the given calendar year.
- get_energysecurity_cf(batch_settings, calendar_year)
Get energy security cost factors
- Parameters:
batch_settings – an instance of the BatchSettings class.
calendar_year – The calendar year for which energy security related factors are needed.
- Returns:
A list of cost factors as specified in the cost_factors list for the given calendar year.
- calc_delta(dict_na, dict_a, arg)
Calculate the delta between sessions for a given attribute.
- Parameters:
dict_na (dict) – the no_action dictionary of data.
dict_a (dict) – the action dictionary of data.
arg (str) – the attribute for which the delta is sought.
- Returns:
The delta between no_action and action sessions for the given attribute.
- calc_benefits(batch_settings, annual_physical_effects_df, annual_cost_effects_df, calc_health_effects=False)
- Parameters:
batch_settings – an instance of the BatchSettings class.
annual_physical_effects_df (DataFrame) – a DataFrame of physical effects by calendar year, reg class, fuel type.
annual_cost_effects_df (DataFrame) – a DataFrame of cost effects by calendar year, reg class, fuel type.
calc_health_effects (bool) – pass True to use $/ton values to calculate health effects. If cost_factors_criteria.csv
values (contains benefit per ton) –
False. (calc_health_effects will be True; blank values will result in the default) –
- Returns:
one of benefits for each action session relative to the no_action session; and one of physical effects for each action session relative to the no_action session.
- Return type:
Two dictionaries
- build_dicts(batch_settings, calc_health_effects, physical_a=None, physical_na=None, cost_a=None, cost_na=None, key_a=None)
- Parameters:
batch_settings – an instance of the BatchSettings class.
calc_health_effects (bool) – if True the criteria air pollutant health effects will be calculated.
physical_a (dict) – the physical effects for the action session for a given “vehicle.”
physical_na (dict) – the physical effects for the no_action session for a given “vehicle.”
cost_a (dict) – the cost effects for the action session for a given “vehicle.”
cost_na (dict) – the cost effects for the no_action session for a given “vehicle.”
key_a (tuple) – the physical effects dictionary key for the given “vehicle.”
- Returns:
A dictionary of benefits for the given “vehicle” and a dictionary of physical effect impacts for that “vehicle.”
7.1.1.3.3. omega_effects.effects.context_fuel_cost_per_mile module
Function to calculate fuel costs per mile in the reference session against which rebound effects can be calculated for subsequent sessions.
CODE
- calc_context_fuel_cost_per_mile(batch_settings, session_settings)
- Parameters:
batch_settings – an instance of the BatchSettings class.
session_settings – an instance of the SessionSettings class.
- Returns:
A dictionary of fuel costs per mile by vehicle_id and age.
7.1.1.3.4. omega_effects.effects.cost_effects module
A series of functions to calculate costs associated with the policy. The calc_cost_effects function is called by the omega_effects_main module and other functions here are called from within the calc_cost_effects function.
CODE
- get_congestion_noise_cf(batch_settings, reg_class_id)
Get congestion and noise cost factors
- Parameters:
batch_settings – an instance of the BatchSettings class.
reg_class_id (str) – The (legacy) regulatory class ID for which congestion and noise cost factors are needed.
- Returns:
A list of cost factors as specified in the cost_factors list for the given calendar year.
- get_maintenance_cost(batch_settings, veh_type)
- Parameters:
batch_settings – an instance of the BatchSettings class.
veh_type – (str) ‘BEV’, ‘PHEV’, ‘ICE’, ‘HEV’
- Returns:
Curve coefficient values to calculate maintenance costs per mile at any odometer value.
- calc_cost_effects(batch_settings, session_settings, session_fleet_physical, context_fuel_cpm_dict)
Calculate cost effects
- Parameters:
batch_settings – an instance of the BatchSettings class.
session_settings – an instance of the SessionSettings class.
session_fleet_physical – A dictionary of physical effects for each vehicle in each analysis year.
context_fuel_cpm_dict – dictionary; the context session fuel costs per mile by vehicle_id and age.
- Returns:
A dictionary of cost effects for each vehicle in each analysis year.
Notes
The average purchase price will include possible battery tax credits and reflects the expected price of a vehicle on the dealer lot. The average price modification reflects possible purchase tax credits which would be deducted from the average purchase price to reflect out-of-pocket purchase costs. Insurance, sales taxes, and any other cost tied to the value of a vehicle use the average purchase price in applicable calculations. An exception to that would be repair costs which are tied to the manufacturer cost and not purchase prices. The manufacturer cost excludes cost reductions via applicable battery tax credits.
- calc_annual_cost_effects(input_df)
- Parameters:
input_df (DataFrame) – cost effects by vehicle in each analysis year.
- Returns:
A DataFrame of cost effects by calendar year, reg class and fuel type.
- calc_period_consumer_view(batch_settings, input_df, periods)
- Parameters:
batch_settings – an instance of the BatchSettings class.
input_df (DataFrame) – cost effects by vehicle in each analysis year.
periods (int) – the number of periods (years) to include in the consumer view, set via the
general_inputs_for_effects_file. –
- Returns:
A DataFrame of cost effects by model year of available lifetime, body style and fuel type.
7.1.1.3.5. omega_effects.effects.cost_factors_congestion_noise module
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows.
The data represents $/mile cost estimates associated with congestion and noise associated with road travel.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
cost_factors_congestion_noise
input_template_version:
0.1
- Sample Data Columns
reg_class_id
dollar_basis
congestion_cost_dollars_per_mile
noise_cost_dollars_per_mile
car
2018
0.063390239
0.000940863
truck
2018
0.056598428
0.000940863
Data Column Name and Description
- reg_class_id:
Vehicle regulatory class at the time of certification, e.g. ‘car’,’truck’. Reg class definitions may differ across years within the simulation based on policy changes.
reg_class_id
can be considered a ‘historical’ or ‘legacy’ reg class.- dollar_basis:
The dollar basis of values within the table. Values are converted in-code to ‘analysis_dollar_basis’ using the implicit_price_deflators input file.
- congestion_cost_dollars_per_mile:
The cost per vehicle mile traveled associated with congestion.
- noise_cost_dollars_per_mile:
The cost per vehicle mile traveled associated with noise.
CODE
- class CostFactorsCongestionNoise
Bases:
object
Loads and provides access to congestion and noise cost factors by legacy reg class id.
- __init__()
- init_from_file(filepath, batch_settings, effects_log)
Initialize class data from input file.
- Parameters:
filepath – the Path object to the file.
batch_settings – an instance of the BatchSettings class.
effects_log – an instance of the EffectsLog class.
- Returns:
Nothing, but reads the appropriate input file.
- get_cost_factors(reg_class_id, cost_factors)
Get cost factors by legacy reg class id
- Parameters:
reg_class_id (str) – reg class to get cost factors for
cost_factors – name of cost factor or list of cost factor attributes to get
- Returns:
Cost factor or list of cost factors
7.1.1.3.6. omega_effects.effects.cost_factors_criteria module
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows.
The data represents $/uston benefits estimates associated with reductions in criteria air pollutants. The data should be left blank to avoid calculating health effects (criteria air pollution effects) using $/uston values.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
cost_factors_criteria
input_template_version:
0.5
- Sample Data Columns
calendar_year
dollar_basis
source_id
rate
study
pm25
sox
nox
2020
2020
car pump gasoline
0.03
Wu
0
0
0
2025
2020
car pump gasoline
0.03
Wu
709156.4844
127863.083
7233.620573
2030
2020
car pump gasoline
0.03
Wu
813628.2611
146570.4771
8157.897937
2035
2020
car pump gasoline
0.03
Wu
938850.3917
169075.4785
9195.259845
2040
2020
car pump gasoline
0.03
Wu
1060686.72
191135.9472
10073.96999
2045
2020
car pump gasoline
0.03
Wu
1171439.061
211302.6049
10731.06062
2050
2020
car pump gasoline
0.03
Wu
1268468.809
229133.7696
11165.95105
Data Column Name and Description
- calendar_year:
The calendar year for which specific cost factors are applicable.
- dollar_basis:
The dollar basis of values within the table. Values are converted in-code to ‘analysis_dollar_basis’ using the cpi_price_deflators input file.
- source_id:
The source of the pollutant, whether it be a gasoline car or an EGU or refinery.
- rate:
The discount rate used in generating the $/ton benefits values.
- study:
The study from which the values are sourced.
- pm25:
The dollar per US ton of PM2.5.
- sox:
The dollar per US ton of SOx.
- nox:
The dollar per US tons of NOx.
CODE
- class CostFactorsCriteria
Bases:
object
Loads and provides access to criteria emissions cost factors by calendar year.
- __init__()
- init_from_file(filepath, batch_settings, effects_log)
Initialize class data from input file.
- Parameters:
filepath – the Path object to the file.
batch_settings – an instance of the BatchSettings class.
effects_log – an instance of the EffectsLog class.
- Returns:
Nothing, but reads the appropriate input file.
- get_cost_factors(calendar_year, source_id, cost_factors)
Get cost factors by calendar year
- Parameters:
calendar_year (int) – calendar year to get cost factors for
source_id – (str): the pollutant source, e.g., ‘car pump gasoline’, ‘egu’, ‘refinery’
cost_factors (str, [strs]) – name of cost factor or list of cost factor attributes to get
- Returns:
Cost factor or list of cost factors
7.1.1.3.7. omega_effects.effects.cost_factors_energysecurity module
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows.
The data represents $/gallon cost estimates associated with energy security and the share of oil imports reduced as oil demand is reduced.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
cost_factors_energysecurity
input_template_version:
0.3
- Sample Data Columns
calendar_year
dollar_basis
dollars_per_bbl
oil_import_reduction_as_percent_of_total_oil_demand_reduction
2020
2020
3.217039918
0.907
2021
2020
3.143206215
0.907
2022
2020
3.269778277
0.907
Data Column Name and Description
- calendar_year:
The calendar year for which $/barrel values are applicable.
- dollar_basis:
The dollar basis of values within the table. Values are converted in-code to ‘analysis_dollar_basis’ using the implicit_price_deflators input file.
- dollars_per_bbl:
The cost (in US dollars) per barrel of oil associated with energy security.
- oil_import_reduction_as_percent_of_total_oil_demand_reduction:
The reduction in imported oil as a percent of the total oil demand reduction.
CODE
- class CostFactorsEnergySecurity
Bases:
object
Loads and provides access to energy security cost factors by calendar year.
- __init__()
- init_from_file(filepath, batch_settings, effects_log)
Initialize class data from input file.
- Parameters:
filepath – the Path object to the file.
batch_settings – an instance of the BatchSettings class.
effects_log – an instance of the EffectsLog class.
- Returns:
Nothing, but reads the appropriate input file.
- get_cost_factors(calendar_year, cost_factors)
Get cost factors by calendar year
- Parameters:
calendar_year (int) – calendar year to get cost factors for
cost_factors (str, [strs]) – name of cost factor or list of cost factor attributes to get
- Returns:
Cost factor or list of cost factors
7.1.1.3.8. omega_effects.effects.cost_factors_scghg module
INPUT FILE FORMAT
The file format consists of a one-row data header and subsequent data rows.
The data represent the social costs per ton associated with emissions of GHGs.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
cost_factors_scghg
input_template_version:
0.4
- Sample Data Columns
gas
calendar_year
dollar_basis
scope
0.025
0.02
0.015
co2
2020
2020
global
117
193
337
co2
2021
2020
global
119
197
341
co2
2022
2020
global
122
200
346
co2
2023
2020
global
125
204
351
co2
2024
2020
global
128
208
356
- Data Column Name and Description
- gas:
The pollutant, e.g., co2, ch4 or n2o.
- calendar_year:
The calendar year, an integer.
- dollar_basis:
The dollar basis of the dollars_per_metricton values; values are converted to analysis dollars in-code.
- scope:
The scope of the valuations, e.g., global or domestic.
- remaining column headers:
These headers should indicate the discount rate(s) used in generating the valuations.
CODE
- class CostFactorsSCGHG
Bases:
object
Loads and provides access to social cost of carbon cost factors by calendar year.
- __init__()
- init_from_file(filepath, batch_settings, effects_log)
Initialize class data from input file.
- Parameters:
filepath – the Path object to the file.
batch_settings – an instance of the BatchSettings class.
effects_log – an instance of the EffectsLog class.
- Returns:
Nothing, but reads the appropriate input file.
- get_factors(calendar_year)
- Parameters:
calendar_year (int) – the calendar year for which emission cost factors are needed.
- Returns:
A dictionary of dollar per ton cost factors for the passed year_id.
7.1.1.3.9. omega_effects.effects.discounting_benefits module
OMEGA effects discounting module for benefits.
CODE
- class DiscountingBenefits
Bases:
object
The DiscountingBenefits class discounts annual values, sums those to calculate present values and annualizes those present values for equivalent annualized values.
- __init__()
- discount_annual_values(batch_settings, annual_values_df, effects_log)
The discount_annual_values function determines attributes appropriate for discounting and does the discounting calculation to a given year and point within that year.
- Parameters:
batch_settings – an instance of the omega effects batch settings class.
annual_values_df (DataFrame) – including values to be discounted.
effects_log – an instance of the EffectsLog class.
- Returns:
A dictionary providing discounted annual values where monetized values are discounted at their internally consistent discount rate.
Note
Important input settings for discounting of monetized values are the “Discount Values to Year” and “Cost Accrual” settings. The year to which to discount monetized values is set by the “Discount Values to Year” entry of the omega effects batch input file. The “Cost Accrual” input setting should be set to ‘start-of-year’ or ‘end-of-year’, where start-of-year represents costs accruing at time t=0 within the year, and end-of-year represents costs accruing at the end of the year.
Values that occur prior to the “Discount Values to Year” input setting will not be discounted.
Criteria health benefits are generated using $/ton inputs for criteria cost factors. Annual discounted values calculated here are valid only for those social discount rates that match the discount rate used in generating the $/ton benefit values. In other words, annual discounted values using a 2 percent social discount rate are not valid if calculated using a 3 or 7 percent discount rate in generating the $/ton values. That said, this does calculate those values for use in generating present and annualized values of, for example, the 3 percent health benefits using a 2 percent discount rate.
- calc_present_values(batch_settings)
- Parameters:
batch_settings – an instance of the BatchSettings class.
- Returns:
A dictionary of present values based on the discounted annual values in dict_of_values.
- calc_annualized_values(batch_settings)
- Parameters:
batch_settings – an instance of the BatchSettings class.
- Returns:
A dictionary of equivalent annualized values based on the present values in dict_of_values.
- discount_value(arg_value, rate, year, discount_to, cost_accrual)
- Parameters:
arg_value (float) – the value to be discounted.
rate (float) – the discount rate to use.
year (int) – the calendar year associated with arg_value.
discount_to (int) – the calendar year to which to discount the value.
cost_accrual (str) – set via the general_inputs file to indicate whether costs occur at the start or end of
year. (the) –
- Returns:
A single value representing arg_value discounted to year discount_to at rate.
- annualize_value(present_value, rate, periods, cost_accrual)
- Parameters:
present_value (float) – the present value to be annualized.
rate (float) – the discount rate to use.
periods (int) – the number of periods over which to annualize present_value.
cost_accrual (str) – set via the general_inputs file to indicate whether costs occur at the start or end of
year. (the) –
- Returns:
A single annualized value of present_value discounted at rate over periods number of year_ids.
7.1.1.3.10. omega_effects.effects.discounting_costs module
OMEGA effects discounting module for costs.
CODE
- class DiscountingCosts
Bases:
object
The DiscountingCosts class discounts annual values, sums those to calculate present values and annualizes those present values for equivalent annualized values.
- __init__()
- discount_annual_values(batch_settings, annual_values_df)
The discount_annual_values function determines attributes appropriate for discounting and does the discounting calculation to a given year and point within that year.
- Parameters:
batch_settings – an instance of the omega effects batch settings class.
annual_values_df (DataFrame) – including values to be discounted.
- Returns:
A dictionary providing discounted annual values where monetized values are discounted at their internally consistent discount rate.
Note
Important input settings for discounting of monetized values are the “Discount Values to Year” and “Cost Accrual” settings. The year to which to discount monetized values is set by the “Discount Values to Year” entry of the omega effects batch input file. The “Cost Accrual” input setting should be set to ‘start-of-year’ or ‘end-of-year’, where start-of-year represents costs accruing at time t=0 within the year, and end-of-year represents costs accruing at the end of the year.
Values that occur prior to the “Discount Values to Year” input setting will not be discounted.
- calc_present_values(batch_settings)
- Parameters:
batch_settings – an instance of the BatchSettings class.
- Returns:
A dictionary of present values based on the discounted annual values in dict_of_values.
- calc_annualized_values(batch_settings)
- Parameters:
batch_settings – an instance of the BatchSettings class.
- Returns:
A dictionary of equivalent annualized values based on the present values in dict_of_values.
- discount_model_year_values(model_year_df)
The discount function determines attributes appropriate for discounting and does the discounting calculation to the first year of any given model year.
- Parameters:
model_year_df (DataFrame) – including values to be discounted.
- Returns:
A DataFrame providing discounted model year values where monetized values are discounted to the first year of the model year.
- discount_value(arg_value, rate, year, discount_to, cost_accrual)
- Parameters:
arg_value (float) – the value to be discounted.
rate (float) – the discount rate to use.
year (int) – the calendar year associated with arg_value.
discount_to (int) – the calendar year to which to discount the value.
cost_accrual (str) – set via the general_inputs file to indicate whether costs occur at the start or end of
year. (the) –
- Returns:
A single value representing arg_value discounted to year discount_to at rate.
- annualize_value(present_value, rate, periods, cost_accrual)
- Parameters:
present_value (float) – the present value to be annualized.
rate (float) – the discount rate to use.
periods (int) – the number of periods over which to annualize present_value.
cost_accrual (str) – set via the general_inputs file to indicate whether costs occur at the start or end of
year. (the) –
- Returns:
A single annualized value of present_value discounted at rate over periods number of year_ids.
7.1.1.3.11. omega_effects.effects.egu_data module
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows.
The data represent electricity generating unit (EGU) data used to generate emission rates for EGU inventory estimates within OMEGA.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
egu_data
input_template_version:
0.1
- Sample Data Columns
calendar_year
case
kwh_demand
kwh_generation_us
sox_metrictons
pm25_metrictons
nox_metrictons
voc_metrictons
co2_metrictons
ch4_metrictons
n2o_metrictons
hg_metrictons
hcl_metrictons
2028
low_demand
79544639445.48
4497701954660.72
351072.8942
67218.07241
409162.2661
33001.24309
1217556478
75270.3264
10333.44158
2.266368225
2356910.393
2030
low_demand
136558511832.60
4670151092867.58
264774.1044
59667.73307
338642.6739
29077.65143
980444588.3
59870.49167
8050.273584
1.924340284
1658513.655
2035
low_demand
251608375612.76
5095669022035.69
119985.3562
42787.22665
197024.4201
23023.12353
619769856.1
36184.84215
4718.077117
1.463955288
844965.4172
2040
low_demand
337855975636.14
5537703812563.29
82765.50429
35133.53722
149311.1201
19945.30642
485460423.1
28218.38031
3658.722776
1.322392791
645510.4954
2045
low_demand
395977141924.21
5950705341882.59
39601.46297
27478.64502
103515.9881
16877.89892
415403127.8
17387.75667
2136.312547
1.055589504
215388.0036
2050
low_demand
429009640863.85
6436548029793.40
16511.33781
24217.59845
87459.74149
15520.55116
363816428.8
13906.12554
1668.277298
0.961601679
117719.2093
Data Column Name and Description
- calendar_year:
The calendar year for which the data are applicable.
- case:
The Integrated Planning Model (IPM) electricity demand case.
- kwh_demand:
The onroad kwh demand used in IPM.
- kwh_generation_us:
The EGU kwh generation used in IPM runs for the United States.
- pollutant_id_metrictons:
The EGU inventory of pollutant_id emissions where pollutant_id can be sox, pm25, nox, voc, co2, ch4, n2o, hg, and hcl. All inventories are in metric tons in the indicated year.
CODE
- class EGUdata
Bases:
object
Loads and provides access to EGU data and emission rates by calendar year.
- __init__()
- init_from_file(filepath, effects_log)
Initialize class data from input file.
- Parameters:
filepath – the Path object to the file.
effects_log – an instance of the EffectsLog class.
- Returns:
Nothing, but reads the appropriate input file.
- calc_rates(df)
- Parameters:
df (DataFrame) – The egu input data.
- Returns:
A DataFrame of egu emission rates based on the input data.
- get_emission_rate(v, cyear, session_kwh_consumption, session_kwh_generation, rate_names)
Get emission rates by calendar year
- Parameters:
v (dict) – a dictionary of annual physical effects values
cyear (int) – calendar year for which to get emission rates
session_kwh_consumption (numeric) – the session kwh to use (e.g., kwh_consumption or kwh_generation; this is omega-only)
session_kwh_generation (numeric) – the session kwh generation needed to satisfy kwh_session.
rate_names (str, [strs]) – name of emission rate(s) to get
- Returns:
A list of emission rates for the given kwh_demand in the given calendar_year.
- interpolate_input_data()
- Returns:
Nothing, but it builds the data dictionary of interpolated inputs based on the limited years of input data.
7.1.1.3.12. omega_effects.effects.egu_inventory module
- get_egu_emission_rate(batch_settings, v, calendar_year, kwh_consumption, kwh_generation)
- Parameters:
batch_settings – an instance of the BatchSettings class.
v (dict) – a dictionary of annual physical effects values.
calendar_year (int) – The calendar year for which egu emission rates are needed.
kwh_consumption (float) – The energy consumed by the fleet measured at the wall or charger outlet.
kwh_generation (float) – The energy generation required to satisfy kwh_consumption.
- Returns:
A list of EGU emission rates for the given calendar year.
- calc_egu_inventory(batch_settings, annual_physical_df)
- Parameters:
batch_settings – an instance of the BatchSettings class
annual_physical_df (DataFrame) – a DataFrame of annual physical effects
- Returns:
The passed physical effects dictionary with EGU inventories included
7.1.1.3.13. omega_effects.effects.emission_rate_curves_vehicles module
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows.
The data represents tailpipe emission rates by model year, age, reg-class and fuel type as estimated by EPA’s MOVES model.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
effects.emission_rate_curves_vehicles
input_template_version:
0.2
- Sample Data Columns
start_year
sourcetype_name
reg_class_id
market_class_id
in_use_fuel_id
rate_name
independent_variable
slope
intercept
ind_variable_data
rate_data
equation
1995
passenger car
car
non_hauling.ICE
pump gasoline
pm25_exhaust_grams_per_mile
age
0.000020575
0.02556
[22, 30]
[0.02601255162083171, 0.026177151337127946]
((2.0575e-05 * age) + 0.02556)
1995
passenger car
car
non_hauling.ICE
pump gasoline
nmog_exhaust_grams_per_mile
age
-0.00059478
0.77323
[22, 30]
[0.7601447516760625, 0.7553865333609487]
((-0.00059478 * age) + 0.77323)
- Data Column Name and Description
- start_year:
The model year to which the rate applies; model years not shown will apply the start_year rate less than or equal to the model year.
- sourcetype_name:
The MOVES sourcetype name (e.g., passenger car, passenger truck, light-commercial truck, etc.).
- reg_class_id:
Vehicle regulatory class at the time of certification, e.g. ‘car’,’truck’. Reg class definitions may differ across years within the simulation based on policy changes.
reg_class_id
can be considered a ‘historical’ or ‘legacy’ reg class.- market_class_id:
The OMEGA market class (e.g., non-hauling.ICE, hauling.BEV, etc.).
- in_use_fuel_id:
In-use fuel id, for use with context fuel prices, must be consistent with the context data read by
class context_fuel_prices.ContextFuelPrices
- rate_name:
The emission rate providing the pollutant and units.
- independent_variable:
The independent variable used in calculating the emission rate (e.g., age).
- slope:
The slope of the linear fit to the emission rate input data.
- intercept:
The intercept of the linear fit to the emission rate input data.
- ind_variable_data:
Input data for the independent variable used to generate the emission rate curve where data represent the age associated with the corresponding input data.
- rate_data:
The emission rate data used to generate the emission rate curve.
- equation:
The linear fit emission rate equation used to calculate an emission rate at the given independent variable.
CODE
- class EmissionRatesVehicles
Bases:
object
Loads and provides access to vehicle emission factors by model year, age, legacy reg class ID and in-use fuel ID.
- __init__()
- init_from_file(filepath, effects_log)
Initialize class data from input file.
- Parameters:
filepath – the Path object to the file.
effects_log – an instance of the EffectsLog class.
- Returns:
Nothing, but reads the appropriate input file.
- get_emission_rate(session_settings, model_year, sourcetype_name, reg_class_id, in_use_fuel_id, age)
- Parameters:
session_settings – an instance of the SessionSettings class
model_year (int) – vehicle model year for which to get emission factors
sourcetype_name (str) – the MOVES sourcetype name (e.g., ‘passenger car’, ‘light commercial truck’)
reg_class_id (str) – the regulatory class, e.g., ‘car’ or ‘truck’
in_use_fuel_id (str) – the liquid fuel ID, e.g., ‘pump gasoline’
age (int) – vehicle age in years
- Returns:
A list of emission rates for the given type of vehicle of the given model_year and age.
7.1.1.3.14. omega_effects.effects.emission_rates_egu module
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows.
The data represents electricity generating unit emission rates by calendar year.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
emission_rates_egu
input_template_version:
0.3
- Sample Data Columns
calendar_year
case
kwh_consumption_low_bound
kwh_generation_us
pm25_grams_per_kwh
nox_grams_per_kwh
sox_grams_per_kwh
voc_grams_per_kwh
co_grams_per_kwh
co2_grams_per_kwh
ch4_grams_per_kwh
n2o_grams_per_kwh
hg_grams_per_kwh
hcl_grams_per_kwh
2028
low_demand
7.95E+10
4.5E+12
0.014937349
0.090888889
0.078
7.33E-03
2.22222E-13
271.1111111
0.016733333
0.00229
5.04444E-07
0.524444444
2029
low_demand
1.08E+11
4.585E+12
0.013857083
0.081739948
0.067372591
6.78E-03
2.18178E-13
240.4806091
0.014779943
2.01E-03
4.5779E-07
0.439952415
2030
low_demand
1.37E+11
4.67E+12
0.012776817
0.072591006
0.056745182
6.23E-03
2.14133E-13
209.8501071
0.012826552
0.00172
4.11135E-07
0.355460385
Data Column Name and Description
- calendar_year:
The calendar year for which rates are sought.
- case:
The Integrated Planning Model (IPM) electricity demand case.
- kwh_consumption_low_bound:
The onroad kwh consumption used in IPM.
- kwh_generation_us:
The US EGU kwh demand used in IPM.
- pm25_grams_per_kwh:
The PM2.5 grams per kwh generated at the EGU.
- nox_grams_per_kwh:
The NOx grams per kwh generated at the EGU.
- sox_grams_per_kwh:
The SOx grams per kwh generated at the EGU.
- voc_grams_per_kwh:
The VOC grams per kwh generated at the EGU.
- co_grams_per_kwh:
The CO grams per kwh generated at the EGU.
- co2_grams_per_kwh:
The CO2 grams per kwh generated at the EGU.
- ch4_grams_per_kwh:
The CH4 grams per kwh generated at the EGU.
- n2o_grams_per_kwh:
The N2O grams per kwh generated at the EGU.
- hg_grams_per_kwh:
The Hg grams per kwh generated at the EGU.
- hcl_grams_per_kwh:
The HCl grams per kwh generated at the EGU.
CODE
- class EmissionRatesEGU
Bases:
object
Loads and provides access to power sector emissions factors by calendar year.
- __init__()
- init_from_file(filepath, effects_log)
Initialize class data from input file.
- Parameters:
filepath – the Path object to the file.
effects_log – an instance of the EffectsLog class.
- Returns:
Nothing, but reads the appropriate input file.
- get_emission_rate(session_settings, cyear, session_kwh_consumption, session_kwh_generation, rate_names)
Get emission rates by calendar year
- Parameters:
session_settings – an instance of the SessionSettings class
cyear (int) – calendar year for which to get emission rates
session_kwh_consumption (numeric) – the session kwh to use (e.g., kwh_consumption or kwh_generation; this is omega-only)
session_kwh_generation (numeric) – the session kwh generation needed to satisfy kwh_session.
rate_names (str, [strs]) – name of emission rate(s) to get
- Returns:
A list of emission rates for the given kwh_demand in the given calendar_year.
- interpolate_input_data()
- Returns:
Nothing, but it builds the data dictionary of interpolated inputs based on the limited years of input data.
7.1.1.3.15. omega_effects.effects.emission_rates_refinery module
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows.
The data represents refinery emission rate curves.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
emission_rates_refinery
input_template_version:
0.2
- Sample Data Columns
calendar_year
co_grams_per_gallon
co2_grams_per_gallon
n2o_grams_per_gallon
nox_grams_per_gallon
pm25_grams_per_gallon
sox_grams_per_gallon
voc_grams_per_gallon
2030
0.221366923
776.3322717
0.006565074
0.333376711
0.079500558
0.099981211
0.23941677
2031
0.225401153
790.8154639
0.006687551
0.339531504
0.080958362
0.101826973
0.24376566
2032
0.229435383
805.2986561
0.006810029
0.345686296
0.082416166
0.103672736
0.248114551
2033
0.233469613
819.7818483
0.006932506
0.351841089
0.083873971
0.105518498
0.252463441
Data Column Name and Description
- calendar_year:
The calendar year for which rates are sought.
- co_grams_per_gallon:
The CO emission rate in grams per gallon of fuel refined.
- co2_grams_per_gallon:
The CO2 emission rate in grams per gallon of fuel refined.
- n2o_grams_per_gallon:
The N2O emission rate in grams per gallon of fuel refined.
- nox_grams_per_gallon:
The NOx emission rate in grams per gallon of fuel refined.
- pm25_grams_per_gallon:
The PM2.5 emission rate in grams per gallon of fuel refined.
- sox_grams_per_gallon:
The SOx emission rate in grams per gallon of fuel refined.
- voc_grams_per_gallon:
The VOC emission rate in grams per gallon of fuel refined.
CODE
- class EmissionRatesRefinery
Bases:
object
Loads and provides access to power sector emissions factors by calendar year.
- __init__()
- init_from_file(session_settings, filepath, effects_log)
Initialize class data from input file.
- Parameters:
session_settings – an instance of the SessionSettings class.
filepath – the Path object to the file.
effects_log – an instance of the EffectsLog class.
- Returns:
Nothing, but reads the appropriate input file.
- get_emission_rate(calendar_year, rate_names)
Get emission rates by calendar year
- Parameters:
calendar_year (int) – calendar year for which to get emission rates
rate_names (str, [strs]) – name of emission rate(s) to get
- Returns:
A list of emission rates for the given kwh_demand in the given calendar_year.
- interpolate_input_data(session_settings)
- Parameters:
session_settings – an instance of the SessionSettings class.
- Returns:
Nothing, but it builds the data dictionary of interpolated inputs based on the limited years of input data.
7.1.1.3.16. omega_effects.effects.emission_rates_vehicles module
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows.
The data represents vehicle emission rates by model year, age, reg-class and fuel type as estimated by EPA’s MOVES model.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
effects.emission_rates_vehicles
input_template_version:
0.1
- Sample Data Columns
start_year
age
reg_class_id
sourcetype_name
in_use_fuel_id
pm25_exhaust_grams_per_mile
nmog_exhaust_grams_per_mile
acetaldehyde_exhaust_grams_per_mile
acrolein_exhaust_grams_per_mile
benzene_exhaust_grams_per_mile
13_butadiene_exhaust_grams_per_mile
ethylbenzene_exhaust_grams_per_mile
formaldehyde_exhaust_grams_per_mile
naphthalene_exhaust_grams_per_mile
15pah_exhaust_grams_per_mile
thc_exhaust_grams_per_mile
co_exhaust_grams_per_mile
nox_exhaust_grams_per_mile
ch4_exhaust_grams_per_mile
n2o_exhaust_grams_per_mile
nmhc_exhaust_grams_per_mile
pm25_brakewear_grams_per_mile
pm25_tirewear_grams_per_mile
nmog_evap_permeation_grams_per_gallon
nmog_evap_fuel_vapor_venting_grams_per_gallon
nmog_evap_fuel_leaks_grams_per_gallon
nmog_refueling_displacement_grams_per_gallon
nmog_refueling_spillage_grams_per_gallon
benzene_evap_permeation_grams_per_gallon
benzene_evap_fuel_vapor_venting_grams_per_gallon
benzene_evap_fuel_leaks_grams_per_gallon
benzene_refueling_displacement_grams_per_gallon
benzene_refueling_spillage_grams_per_gallon
ethylbenzene_evap_permeation_grams_per_gallon
ethylbenzene_evap_fuel_vapor_venting_grams_per_gallon
ethylbenzene_evap_fuel_leaks_grams_per_gallon
ethylbenzene_refueling_displacement_grams_per_gallon
ethylbenzene_refueling_spillage_grams_per_gallon
naphthalene_refueling_spillage_grams_per_gallon
sox_exhaust_grams_per_gallon
1995
22
car
passenger car
pump gasoline
0.026012552
0.760144752
0.009408835
0.00046439
0.025028029
0.003978624
0.014277742
0.009888105
0.001530756
3.27E-05
0.858350773
17.90824361
2.140360297
0.125313562
0.02561411
0.733036905
0.002771515
0.001283189
7.70485875
19.21041082
11.21596483
4.61563711
0.331955427
0.047341593
0.067338101
0.037754896
0.015598022
0.001133856
0.007728421
0.330846081
0.193164016
0.079491647
0.005717013
0.12715278
1995
23
car
passenger car
pump gasoline
0.026033127
0.759549974
0.009380668
0.000464027
0.025060109
0.003972801
0.01426657
0.009863367
0.001529562
3.28E-05
0.857679295
17.91679716
2.139972443
0.125215512
0.025672278
0.73246352
0.002771514
0.001283188
7.898657131
19.56287328
11.42982548
4.617193593
0.331955378
0.048762991
0.068972206
0.03869661
0.015684556
0.00113956
0.007922814
0.336916293
0.196847155
0.079518442
0.005717012
0.117743255
1995
24
car
passenger car
pump gasoline
0.026053702
0.758955197
0.009352502
0.000463663
0.02509219
0.003966978
0.014255397
0.00983863
0.001528368
3.28E-05
0.857007818
17.92535071
2.139584589
0.125117462
0.025730446
0.731890134
0.002771513
0.001283188
8.092455512
19.91533574
11.64368614
4.618750075
0.33195533
0.050184389
0.070606311
0.039638324
0.015771089
0.001145263
0.008117207
0.342986504
0.200530294
0.079545237
0.005717011
0.108333729
- Data Column Name and Description
- start_year:
The model year to which the rate applies; model years not shown will apply the start_year rate less than or equal to the model year.
- age:
The vehicle age within its model year.
- reg_class_id:
Vehicle regulatory class at the time of certification, e.g. ‘car’,’truck’. Reg class definitions may differ across years within the simulation based on policy changes.
reg_class_id
can be considered a ‘historical’ or ‘legacy’ reg class.- sourcetype_name:
The MOVES sourcetype name (e.g., passenger car, passenger truck, light-commercial truck, etc.).
- in_use_fuel_id:
In-use fuel id, for use with context fuel prices, must be consistent with the context data read by
class context_fuel_prices.ContextFuelPrices
- rate_name:
The emission rate providing the pollutant, the source (e.g., exhaust, evap, refueling) and units (e.g., ‘grams_per_mile’ or ‘grams_per_gallon’
CODE
- class EmissionRatesVehicles
Bases:
object
Loads and provides access to vehicle emission factors by model year, age, legacy reg class ID and in-use fuel ID.
- __init__()
- init_from_file(filepath, effects_log)
Initialize class data from input file.
- Parameters:
filepath – the Path object to the file.
effects_log – an instance of the EffectsLog class.
- Returns:
Nothing, but reads the appropriate input file.
- get_emission_rate(session_settings, model_year, sourcetype_name, reg_class_id, in_use_fuel_id, age)
- Parameters:
session_settings – an instance of the SessionSettings class
model_year (int) – vehicle model year for which to get emission factors
sourcetype_name (str) – the MOVES sourcetype name (e.g., ‘passenger car’, ‘light commercial truck’)
reg_class_id (str) – the regulatory class, e.g., ‘car’ or ‘truck’
in_use_fuel_id (str) – the liquid fuel ID, e.g., ‘pump gasoline’
age (int) – vehicle age in years
- Returns:
A list of emission rates for the given type of vehicle of the given model_year and age.
7.1.1.3.17. omega_effects.effects.fatality_rates module
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows.
The data represent fatality rates (fatalities per billion miles) for the fleet.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
fatality_rates
input_template_version:
0.1
- Sample Data Columns
model_year
calendar_year
age
average_fatality_rate
1996
1996
0
8.487042
1996
1997
1
8.364596
1996
1998
2
8.342017
- Data Column Name and Description
- model_year:
The model year of a given vehicle
- calendar_year:
The calendar year
- age:
The vehicle age
- average_fatality_rate:
The fatality rate in fatalities per billions miles travelled where “average” denotes the average effectiveness of passenger safety technology on vehicles.
CODE
- class FatalityRates
Bases:
object
Loads and provides access to fatality rates by calendar year and vehicle age.
- __init__()
- init_from_file(filepath, effects_log)
Initialize class data from input file.
- Parameters:
filepath – the Path object to the file.
effects_log – an instance of the EffectsLog class.
- Returns:
Nothing, but reads the appropriate input file.
- get_fatality_rate(model_year, age)
- Parameters:
model_year (int) – the model year for which a fatality rate is needed.
age (age) – vehicle age in years
- Returns:
The average fatality rate for vehicles of a specific model year and age.
7.1.1.3.18. omega_effects.effects.legacy_fleet module
Routines to load and access legacy fleet data for effects modeling
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows.
The data represent the legacy fleet that ages out as new vehicles enter the fleet.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
legacy_fleet
input_template_version:
0.1
- Sample Data Columns
model_year
age
calendar_year
reg_class_id
body_style
market_class_id
in_use_fuel_id
registered_count
miles_per_gallon
kwh_per_mile
curbweight_lbs
transaction_price_dollars
1981
41
2022
car
sedan
sedan_wagon.ICE
{‘pump gasoline’:1.0}
7819790.332
21.41631
3076
22653.68813
1982
40
2022
car
sedan
sedan_wagon.ICE
{‘pump gasoline’:1.0}
7091909.547
22.21184
3053
23890.97149
1983
39
2022
car
sedan
sedan_wagon.ICE
{‘pump gasoline’:1.0}
7370905.119
22.09123
3112
24881.29373
1984
38
2022
car
sedan
sedan_wagon.ICE
{‘pump gasoline’:1.0}
10108067.31
22.4419
3101
24854.47564
1985
37
2022
car
sedan
sedan_wagon.ICE
{‘pump gasoline’:1.0}
10279557.36
23.01593
3096
25883.12766
- Data Column Name and Description
- model_year:
The model year of vehicles represented by the data
- age:
The age of the vehicles represetned by the data
- calendar_year:
The calendar year for which the data apply
- reg_class_id:
The OMEGA reg_class_id (e.g., ‘car’, ‘truck’)
- body_style:
The OMEGA body_style (e.g., ‘sedan’, ‘pickup’)
- market_class_id:
The OMEGA market class id (e.g., ‘sedan_wagon.BEV’, ‘pickup.ICE’)
- in_use_fuel_id:
The OMEGA in use fuel id and share (e.g., {‘pump gasoline’:1.0}, {‘US electricity’:1.0})
- registered_count:
The number of vehicles of the indicated model year sold as new (this is not the number of vehicles in the fleet in the indicated calendar year)
- miles_per_gallon:
The average 2-cycle fuel economy of the vehicles when sold as new
- kwh_per_mile:
The energy consumption in kilowatt hours of the vehicles when sold as new (electric-only)
- curbweight_lbs:
The curb weight in pounds
- transaction_price_dollars:
The average transaction price of the vehicles when sold as new
CODE
- class LegacyFleet
Bases:
object
Legacy fleet class definition.
- __init__()
Loads and provides access to legacy fleet data by model year and age.
- init_from_file(filepath, vehicles_base_year, effects_log)
Initialize class data from input file.
- Parameters:
filepath – the Path object to the file.
vehicles_base_year (int) – the model year of the input fleet - the legacy fleet calendar year will be
analysis. (adjusted if necessary for consistency with the) –
effects_log – an instance of the EffectsLog class.
- Returns:
Nothing, but reads the appropriate input file.
- update_legacy_fleet(vehicle_id, calendar_year, update_dict)
- Parameters:
vehicle_id (int) – the vehicle_id.
calendar_year (int) – the calendar year.
update_dict (dict) – represents the attribute-value pairs to be updated.
- Returns:
Nothing, but updates the object dictionary with update_dict
- build_legacy_fleet_for_analysis(batch_settings)
- Parameters:
batch_settings – an instance of the BatchSettings class.
- Returns:
Nothing, but it builds and updates the instance dictionary.
- get_legacy_fleet_price(vehicle_id, calendar_year)
- Parameters:
vehicle_id (int) – the vehicle id.
calendar_year (int) – the calendar year.
- Returns:
The transaction price of the vehicle.
- get_adjusted_legacy_fleet_odometer(vehicle_id, calendar_year)
- Parameters:
vehicle_id (int) – the vehicle_id number.
calendar_year (int) – the calendar year for which the vehicle’s odometer value is sought.
Returns:
- adjust_legacy_fleet_stock_and_vmt(batch_settings, vmt_adjustments_session)
- Parameters:
batch_settings – an instance of the BatchSettings class.
vmt_adjustments_session – an instance of the AdjustmentsVMT class.
- Returns:
The legacy fleet with adjusted VMT, registered count and odometer that adjust for context stock and VMT expectations.
Note
There is no rebound VMT calculated for the legacy fleet.
- static set_legacy_fleet_name(vehicle_id, market_class_id, fueling_class)
- Parameters:
vehicle_id (int) – the vehicle id number
market_class_id (str) – the legacy fleet market class id
fueling_class (str) – ‘BEV’, ‘ICE’, ‘PHEV’
- Returns:
A name for the vehicle primarily for use in cost_effects, repair cost calculations which looks for ‘car’ or ‘Pickup’ in the name attribute
Note
This method is called in safety_effects.calc_legacy_fleet_safety_effects
- static set_legacy_fleet_powertrain_type(market_class_id)
- Parameters:
market_class_id (str) – the legacy fleet market class id
- Returns:
A powertrain type for the vehicle primarily for use in cost_effects, repair cost calculations which looks for ‘car’ or ‘Pickup’ in the name attribute
Note
This method is called in safety_effects.calc_legacy_fleet_safety_effects
7.1.1.3.19. omega_effects.effects.physical_effects module
Functions to get vehicle data based on vehicle ID, vehicle emission rates for the given vehicle model year and reg-class, refinery and electricity generating unit emission rates for the given calendar year, and then to calculate from them the pollutant inventories, including fuel consumed, for each year in the analysis.
CODE
- get_inputs_for_effects(batch_settings, arg=None)
- Parameters:
batch_settings – an instance of the BatchSettings class.
arg (str) – The attribute for which an attribute value is needed.
- Returns:
A list of necessary input values for use in calculating effects; use index=[0] if passing a single attribute.
- calc_physical_effects(batch_settings, session_settings, analysis_fleet_safety)
- Parameters:
batch_settings – an instance of the BatchSettings class.
session_settings – an instance of the SessionSettings class.
analysis_fleet_safety – the analysis fleet safety effects.
- Returns:
A dictionary of physical effects for the analysis fleet.
Notes
battery_kwh from the vehicle.csv file represents kwh/veh, not kwh/veh * registered_count; as such, that attribute_name is changed to battery_kwh_per_veh in the effects calculations meaning that battery_kwh becomes the attribute_name that represents kwh/veh * registered_count
- calc_legacy_fleet_physical_effects(batch_settings, session_settings, legacy_fleet_safety)
- Parameters:
batch_settings – an instance of the BatchSettings class.
session_settings – an instance of the SessionSettings class.
legacy_fleet_safety (dict) – the legacy fleet safety effects.
- Returns:
A dictionary of legacy fleet physical effects.
Note
This function must not be called until AFTER calc_physical_effects so that the EGU rates will have been generated using the energy consumption there. This means that legacy fleet electricity consumption is not included when calculating the EGU rates used in the analysis. The legacy fleet electricity consumption is small and gets smaller with each future year making this a minor, if not acceptably negligible, impact.
- calc_annual_physical_effects(batch_settings, input_df)
- Parameters:
batch_settings – an instance of the BatchSettings class.
input_df (DataFrame) – DataFrame of physical effects by vehicle.
- Returns:
A DataFrame of physical effects by calendar year.
Notes
battery_kwh here is kwh/veh * registered_count (not kwh/veh)
- calc_period_consumer_physical_view(input_df, periods)
- Parameters:
input_df (DataFrame) – DataFrame of physical effects by vehicle in each analysis year.
periods (int) – the number of periods (years) to include in the consumer view, set via the
general_inputs_for_effects_file. –
- Returns:
A DataFrame of physical effects by model year of available lifetime, body style and fuel type.
7.1.1.3.20. omega_effects.effects.refinery_data module
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows.
The data represent refinery data used to generate emission rates for refinery inventory estimates within OMEGA.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
refinery_data
input_template_version:
0.1
- Sample Data Columns
calendar_year
fuel_reduction_leading_to_reduced_domestic_refining
onroad_fuel_refinery_co_ustons
onroad_fuel_refinery_co2_ustons
onroad_fuel_refinery_ch4_ustons
onroad_fuel_refinery_n2o_ustons
onroad_fuel_refinery_nox_ustons
onroad_fuel_refinery_pm25_ustons
onroad_fuel_refinery_sox_ustons
onroad_fuel_refinery_voc_ustons
co_emission_apportionment_gasoline
co2_emission_apportionment_gasoline
ch4_emission_apportionment_gasoline
n2o_emission_apportionment_gasoline
nox_emission_apportionment_gasoline
pm25_emission_apportionment_gasoline
sox_emission_apportionment_gasoline
voc_emission_apportionment_gasoline
co_emission_apportionment_diesel
co2_emission_apportionment_diesel
ch4_emission_apportionment_diesel
n2o_emission_apportionment_diesel
nox_emission_apportionment_diesel
pm25_emission_apportionment_diesel
sox_emission_apportionment_diesel
voc_emission_apportionment_diesel
retail_gasoline_million_barrels_per_day
diesel_million_barrels_per_day
other_million_barrels_per_day
net_exports_million_barrels_per_day
gasoline_exports_million_barrels_per_day
diesel_exports_million_barrels_per_day
product_exports_million_barrels_per_day
export_scaler
context_scaler_car_gasoline
context_scaler_truck_gasoline
context_scaler_mediumduty_gasoline
context_scaler_car_diesel
context_scaler_truck_diesel
context_scaler_mediumduty_diesel
2030
0.5
50462.97861
179019969.9
9608.310168
1529.019319
75349.63788
17737.65461
22955.33617
57273.72581
0.602405743
0.591
0.639935949
0.582657883
0.609500939
0.620404538
0.596420189
0.570155224
0.057134474
0.061
0.052711594
0.062889415
0.05570409
0.053464368
0.058421274
0.058337953
8.115856
3.312032
8.154782
6.082668
0.867
1.011
3.087
1.525625282
0.316962715
0.617086695
0.06595059
0.017490849
0.111502501
0.87100665
2035
0.5
50497.76358
179497794.8
9583.178366
1533.100448
75483.7425
17759.06091
22996.09832
57297.53722
0.602405743
0.591
0.639935949
0.582657883
0.609500939
0.620404538
0.596420189
0.570155224
0.057134474
0.061
0.052711594
0.062889415
0.05570409
0.053464368
0.058421274
0.058337953
7.609757
3.221002
8.465063
6.562512
0.867
1.011
3.087
1.645977427
0.249231644
0.675120958
0.075647398
0.006043383
0.137434554
0.856522062
2040
0.5
50829.41372
180908447.2
9620.738704
1545.148906
76168.63053
17883.352
23133.89863
57416.13093
0.602405743
0.591
0.639935949
0.582657883
0.609500939
0.620404538
0.596420189
0.570155224
0.057134474
0.061
0.052711594
0.062889415
0.05570409
0.053464368
0.058421274
0.058337953
7.299925
3.191927
8.794727
6.797757
0.867
1.011
3.087
1.704980436
0.208930401
0.708259977
0.082809622
0.001546558
0.152468031
0.845985411
2045
0.5
51266.15504
183618187.9
9662.433075
1568.292949
76944.91407
18054.04705
23316.37403
57608.23559
0.602405743
0.591
0.639935949
0.582657883
0.609500939
0.620404538
0.596420189
0.570155224
0.057134474
0.061
0.052711594
0.062889415
0.05570409
0.053464368
0.058421274
0.058337953
7.234634
3.196052
9.160675
6.858117
0.867
1.011
3.087
1.720119639
0.195203495
0.71804962
0.086746885
0.000148156
0.154498952
0.845352891
2050
0.5
51793.53884
186521729.1
9743.280669
1593.092253
77829.83767
18253.15804
23501.20676
57829.42994
0.602405743
0.591
0.639935949
0.582657883
0.609500939
0.620404538
0.596420189
0.570155224
0.057134474
0.061
0.052711594
0.062889415
0.05570409
0.053464368
0.058421274
0.058337953
7.431168
3.204183
9.527437
6.431421
0.867
1.011
3.087
1.613097818
0.189893857
0.719549292
0.090556851
1.08646E-05
0.150382554
0.849606582
Data Column Name and Description
- calendar_year:
The calendar year for which the data are applicable.
- fuel_reduction_leading_to_reduced_domestic_refining:
The share of fuel savings that result in reduced domestic refining.
- onroad_fuel_refinery_pollutant_id_ustons:
The pollutant_id inventory in US (short) tons where pollutant_id can be co, co2, n2o, nox, pm25, sox, voc. These inventories represent emissions from refineries that refine onroad fuel.
- pollutant_id_emission_apportionment_gasoline:
The portion of refinery emissions attributable to the pollutant_id when refining gasoline.
- pollutant_id_emission_apportionment_diesel:
The portion of refinery emissions attributable to the pollutant_id when refining diesel.
- retail_gasoline_million_barrels_per_day:
The retail gasoline gallons used in generating refinery emission rates.
- diesel_million_barrels_per_day:
The diesel gallons used in generating refinery emission rates.
- other_million_barrels_per_day:
The other petroleum products used in generating refinery emission rates.
- net_exports_million_barrels_per_day:
The net exports of petroleum products outside the United States.
- gasoline_exports_million_barrels_per_day:
The US exports of gasoline in 2022 used to estimate the share of future net exports that are gasoline.
- diesel_exports_million_barrels_per_day:
The US exports of 15 ppm low sulfur diesel fuel in 2022 used to estimate the share of future net exports that are 15 ppm low sulfur diesel fuel.
- product_exports_million_barrels_per_day:
The US exports of other petroleum products in 2022 used to estimate the share of future net exports that are other petroleum products.
- export_scaler:
A scaler used to project future growth in US petroleum product exports.
- context_scaler_regclass_id_fuel:
A scaler used to estimate the future share of the indicated fuel that is consumed by vehicles of the indicated regclass_id where regclass_id can be car, truck, mediumduty and fuel can be gasoline or diesel.
CODE
- class RefineryData
Bases:
object
Loads and provides access to refinery data and emission rates by calendar year.
- __init__()
- init_from_file(batch_settings, filepath, effects_log)
Initialize class data from input file.
- Parameters:
batch_settings – an instance of the BatchSettings class.
filepath – the Path object to the file.
effects_log – an instance of the EffectsLog class.
- Returns:
Nothing, but reads the appropriate input file.
- calc_rates(batch_settings, df)
- Parameters:
batch_settings – an instance of the BatchSettings class.
df (DataFrame) – the refinery input data.
- Returns:
A DataFrame of refinery emission rates based on the input data.
- get_data(calendar_year, reg_class_id, fuel, *args)
Get emission rates by calendar year
- Parameters:
calendar_year (int) – calendar year for which to get emission rates
reg_class_id (str) – ‘car’, ‘truck’, ‘mediumduty’
fuel (str) – the fuel of interest, e.g., ‘gasoline’ or ‘diesel’
args (str, [strs]) – attribute name of data to get
- Returns:
A list of refinery data for the given calendar_year.
- interpolate_input_data()
- Returns:
Nothing, but it builds the data dictionary of interpolated inputs based on the limited years of input data.
7.1.1.3.21. omega_effects.effects.refinery_inventory_and_oil_imports module
Refinery Inventory and Oil Imports
CODE
- get_refinery_data(batch_settings, calendar_year, reg_class_id, fuel)
- Parameters:
batch_settings – an instance of the BatchSettings class.
calendar_year (int) – The calendar year for which a refinery emission factors are needed.
reg_class_id (str) – The reg class for which to get context scaler data, i.e., ‘car’, ‘truck’, ‘mediumduty’
fuel (str) – e.g., ‘gasoline’ or ‘diesel’
- Returns:
A list of refinery emission rates as specified in the emission_rates list for the given calendar year.
- get_energysecurity_cf(batch_settings, calendar_year)
- Parameters:
batch_settings – an instance of the BatchSettings class.
calendar_year (int) – The calendar year for which energy security related factors are needed.
- Returns:
A list of cost factors as specified in the cost_factors list for the given calendar year.
Note
In the physical_effects module, oil impacts are calculated, not cost impacts; therefore the “cost factor” returned here is the oil import reduction as a percentage of oil demand reduction.
- calc_inventory(context_gallons, session_gallons, rate, impact_on_refining, delta_calc=True, conversion=1)
- Parameters:
context_gallons (float) – the domestic refining associated with the refinery data
session_gallons (float) – the session liquid fuel consumption
rate (float) – the emission rate for the given pollutant
impact_on_refining (float) – the impact of reduced demand on domestic refining
delta_calc (bool) – True for delta from no_action; False for missing entry in no_action
conversion (int) – the conversion from grams to US tons or metric tons
- Returns:
An inventory value for the given pollutant.
- calc_refinery_inventory_and_oil_imports(batch_settings, annual_physical_df)
- Parameters:
batch_settings – an instance of the BatchSettings class
annual_physical_df (DataFrame) – a DataFrame of annual physical effects
- Returns:
The passed physical effects dictionary with refinery inventories and oil import effects included
Note
For action sessions, both the action and no_action physical effects are needed so that the fuel reductions can be calculated; reduced fuel may or may not result in less refining and oil imports depending on the refinery data setting for the “fuel_reduction_leading_to_reduced_domestic_refining” attribute and the energy security cost factor setting for the “oil_import_reduction_as_percent_of_total_oil_demand_reduction” attribute. Note that there are no oil import effects in the no-action session since the effects apply only to changes in fuel demand.
7.1.1.3.22. omega_effects.effects.safety_effects module
Functions to get vehicle data based on vehicle ID, safety values based on body style and fatality rates based on calendar year and vehicle age, and to calculate fatalities.
CODE
- get_safety_values(session_settings, body_style)
- Parameters:
session_settings – an instance of the SessionSettings class.
body_style (str) – the OMEGA body style (e.g., sedan, cuv_suv, pickup)
- Returns:
The curb weight threshold and percentage changes in fatality rates for weight changes above and below that threshold.
- get_fatality_rate(batch_settings, model_year, age)
- Parameters:
batch_settings – an instance of the BatchSettings class.
model_year (int) – the model year for which a fatality rate is needed.
age (int) – vehicle age in years
- Returns:
The average fatality rate for vehicles of a specific model year and age.
- calc_lbs_changed(base_weight, final_weight)
- Parameters:
base_weight – (numeric); base curb weight in pounds
final_weight – (numeric); final curb weight in pounds
- Returns:
The change in curb weight - positive denotes a weight increase, negative a weight decrease.
- calc_lbs_changed_below_threshold(threshold, base_weight, final_weight)
- Parameters:
threshold – (numeric); the curb weight threshold, in pounds, above and below which safety values change
base_weight – (numeric); base curb weight in pounds
final_weight – (numeric); final curb weight in pounds
- Returns:
The portion of the weight change that occurs below the threshold - positive denotes a weight increase, negative a weight decrease.
- calc_lbs_changed_above_threshold(threshold, base_weight, final_weight)
- Parameters:
threshold – (numeric); the curb weight threshold, in pounds, above and below which safety values change
base_weight – (numeric); base curb weight in pounds
final_weight – (numeric); final curb weight in pounds
- Returns:
The portion of the weight change that occurs above the threshold - positive denotes a weight increase, negative a weight decrease.
- calc_safety_effects(batch_settings, session_settings)
- Parameters:
batch_settings – an instance of the BatchSettings class.
session_settings – an instance of the SessionSettings class.
- Returns:
A dictionary of various safety effects, including fatalities.
- calc_legacy_fleet_safety_effects(batch_settings, session_settings)
- Parameters:
batch_settings – an instance of the BatchSettings class.
session_settings – an instance of the SessionSettings class.
- Returns:
A dictionary of various legacy fleet safety effects, including fatalities.
Note
There is no rebound VMT calculated for the legacy fleet.
- calc_annual_avg_safety_effects(input_df)
- Parameters:
input_df (DataFrame) – DataFrame of physical effects by vehicle.
- Returns:
A DataFrame of physical effects by calendar year, regclass, fueling class, etc.
- calc_annual_avg_safety_effects_by_body_style(input_df)
- Parameters:
input_df (DataFrame) – DataFrame of physical effects by vehicle.
- Returns:
A DataFrame of physical effects by calendar year and body style.
7.1.1.3.23. omega_effects.effects.safety_values module
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows.
The data represent safety values associated with mass reduction in the fleet.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
safety_values
input_template_version:
0.1
- Sample Data Columns
body_style
nhtsa_safety_class
threshold_lbs
change_per_100_lbs_below_threshold
change_per_100_lbs_at_or_above_threshold
sedan
PC
3201
0.012
0.0042
pickup
LT/SUV
5014
0.0031
-0.0061
cuv_suv
CUV/Minivan
3872
-0.0025
-0.0025
- Data Column Name and Description
- body_style:
The OMEGA body_style (e.g., sedan, pickup, cuv_suv)
- nhtsa_safety_class:
The NHTSA safety class (e.g., PC, LT/SUV, CUV/Minivan)
- threshold_lbs:
The curb weight, in pounds, above and below which safety values may change.
- change_per_100_lbs_below_threshold:
A percentage change in the fatality rate associated with reductions in curb weight below the associated curb weight threshold; a positive value denotes an increase in fatality rate associated with a reduced curb weight while a negative value denotes a decrease in fatality rate associated with a reduced curb weight; increased curb weights would have the opposite effect on fatality rate.
- change_per_100_lbs_at_or_above_threshold:
A percentage change in the fatality rate associated with reductions in curb weight above the associated curb weight threshold; a positive value denotes an increase in fatality rate associated with a reduced curb weight while a negative value denotes a decrease in fatality rate associated with a reduced curb weight; increased curb weights would have the opposite effect on fatality rate.
CODE
- class SafetyValues
Bases:
object
Loads and provides access to safety values by body style.
- __init__()
- init_from_file(filepath, effects_log)
Initialize class data from input file.
- Parameters:
filepath – the Path object to the file.
effects_log – an instance of the EffectsLog class.
- Returns:
Nothing, but reads the appropriate input file.
- get_safety_values(body_style)
Get safety values by body style.
- Parameters:
body_style (str) – the OMEGA body style (e.g., sedan, cuv_suv, pickup)
- Returns:
The curb weight threshold and percentage changes in fatality rates for weight changes above and below that threshold.
7.1.1.3.25. omega_effects.effects.total_inventory module
Total Inventory module.
CODE
- calc_total_inventory(annual_physical_df)
Calc total inventory
- Parameters:
annual_physical_df (DataFrame) – a DataFrame of annual physical effects
- Returns:
physical_effects_dict with emissions data
7.1.1.3.26. omega_effects.effects.vehicle_annual_data module
OMEGA effects vehicle annual data module.
CODE
- class VehicleAnnualData
Bases:
object
The VehicleAnnualData class reads the vehicle annual data file resulting from the OMEGA compliance run for a given session and adjusts VMT data to account for rebound effects and context expectations that are not applied in the OMEGA compliance run.
- __init__()
- init_from_file(filepath, effects_log)
Initialize class data from input file.
- Parameters:
filepath – the Path object to the file.
effects_log – an instance of the EffectsLog class.
- Returns:
Nothing, but reads the appropriate input file.
- get_vehicle_annual_data_by_calendar_year(calendar_year)
Get vehicle annual data by calendar year.
- Parameters:
calendar_year (int) – the calendar year to retrieve data for
- Returns:
A list of vehicle annual data for the given calendar year.
- get_adjusted_vehicle_annual_data_by_calendar_year(calendar_year)
Get adjusted vehicle annual data by calendar year.
- Parameters:
calendar_year (int) – the calendar year to retrieve data for
- Returns:
A list of adjusted vehicle annual data for the given calendar year.
- get_vehicle_annual_data_by_vehicle_id(calendar_year, vehicle_id, *attribute_names)
Get vehicle annual data by vehicle id.
- Parameters:
calendar_year (int) – the calendar year to retrieve data for
vehicle_id – vehicle id
*attribute_names – the attribute names to retrieve
- Returns:
A list or single value of vehicle annual data by vehicle id.
- adjust_vad(batch_settings, session_settings, vmt_adjustments_session, context_fuel_cpm_dict)
- Parameters:
batch_settings – an instance of the BatchSettings class.
session_settings – an instance of the SessionSettings class.
vmt_adjustments_session – an instance of the AdjustmentsVMT class.
context_fuel_cpm_dict (dict) – the fuel cost per mile dictionary for the batch context.
- Returns:
The vehicle annual data with adjusted VMT and odometer that adjust for rebound and context VMT expectations.
7.1.1.3.27. omega_effects.effects.vehicle_inventory module
Vehicle Physical Effects
- class VehiclePhysicalData
Bases:
object
The VehiclePhysicalData class creates objects containing identifying information and rate information needed to calculate physical effects for a given vehicle.
- __init__()
- update_value(update_dict)
- Parameters:
update_dict (dict) – the class instance attributes as keys along with their values.
- Returns:
Nothing, but it sets class instance attributes to the values contained in update_dict.
- calc_vehicle_inventory(vpd, gwp_list)
- Parameters:
vpd – an instance of the VehiclePhysicalData class.
gwp_list (list) – GWP values for CH4 and N2O, in that order.
- Returns:
A dictionary of physical effects for the given VehiclePhysicalData class instance (vehicle).
7.1.1.3.28. omega_effects.effects.vehicles module
OMEGA effects vehicles module.
CODE
- class Vehicles
Bases:
object
The Vehicles class reads the vehicles file resulting from the OMEGA compliance run for a given session and provides methods to access the data.
- __init__()
- init_from_file(filepath, effects_log)
Initialize class data from input file.
- Parameters:
filepath – the Path object to the file.
effects_log – an instance of the EffectsLog class.
- Returns:
Nothing, but reads the appropriate input file.
- get_vehicle_attributes(vehicle_id, *attribute_names)
Get vehicle attributes by vehicle id and attribute name(s).
- Parameters:
vehicle_id – the vehicle id
*attribute_names (strs) – attributes to retrieve
- Returns:
Vehicle attributes by vehicle id and attribute name(s).
7.1.1.3.29. omega_effects.effects.vmt_adjustments module
Functions to adjust vehicle miles traveled to ensure consistency with projections included in the context_stock_vmt.csv file.
CODE
- class AdjustmentsVMT
Bases:
object
Adjustments VMT class definition.
- __init__()
- calc_vmt_adjustments(batch_settings, session_settings)
- Parameters:
batch_settings – an instance of the BatchSettings class.
session_settings – an instance of the SessionSettings class.
- Returns:
Nothing, but it creates a dictionary of adjusted VMT values by calendar year for use in effects calculations.
- get_vmt_adjustment(calendar_year)
- Parameters:
calendar_year (int) – the calendar year for which the adjustment factor is sought.
- Returns:
The vmt adjustment factor for the passed calendar year.
- get_stock_adjustment(calendar_year)
- Parameters:
calendar_year (int) – the calendar year for which the adjustment factor is sought.
- Returns:
The stock or registered count adjustment factor for the passed calendar year.
7.1.1.4. omega_effects.general package
OMEGA effects general functions subpackage.
CODE
7.1.1.4.1. Submodules
7.1.1.4.2. omega_effects.general.effects_log module
OMEGA effects logging module.
CODE
- class EffectsLog
Bases:
object
Effects log class definition.
- __init__()
- init_logfile(path)
- Parameters:
path – the project Path object.
- logwrite(message, echo_console=True, terminator='\n', stamp=False)
- Parameters:
message (str) – message string to write.
echo_console (bool) – write message to console if True
terminator (str) – end of message terminator, default is newline
stamp (bool) – include date and time stamp True or False
- Returns:
Nothing. Writes message to logfile and to console by default.
7.1.1.4.3. omega_effects.general.file_id_and_save module
OMEGA effects file id and save module.
CODE
- save_file(session_settings, df, save_folder, file_id, effects_log, extension='parquet')
- Parameters:
session_settings – an instance of the SessionSettings class.
df (DataFrame) – the DataFrame to be saved.
save_folder – a Path instance for the save folder.
file_id (str) – file identifier to be included in the saved filename.
effects_log – an instance of the EffectsLog class.
extension (str) – entered in batch settings file (either ‘csv’ or ‘parquet’ with ‘parquet’ the default)
- Returns:
Nothing but saves the passed DataFrame to the save_folder.
Note
If saving files as parquet files, they are readable only by Pandas and cannot be read directly by Excel. To read the parquet file into Pandas, do the following in the Python Console on your IDE: Type ‘import pandas as pd’ without the quotes. Type ‘from pathlib import Path’ without the quotes. Type ‘path = Path(“path to file”)’ without the single quotes but with the double quotes around the path; include double backslash rather than single backslash. Type ‘file = “filename.parquet”’ without the single quotes but with the double quotes. Type ‘df = pd.read_parquet(path / file)’ without the quotes. The DataFrame (df) should contain the contents of the parquet file.
- add_id_to_csv(filepath, output_file_id_info)
- Parameters:
filepath – the Path object to the file.
output_file_id_info (list) – a list of string info to include as output file identifiers.
- Returns:
Nothing, but reads the appropriate input file, inserts a new first row and saves the output_file_id_info in that first row.
7.1.1.4.4. omega_effects.general.general_functions module
OMEGA effects general functions module.
CODE
- copy_files(file_list, folder_name)
- Parameters:
file_list (list) – List of file Path objects to copy into a new location.
folder_name – Path object for the folder into which to copy files.
- Returns:
Nothing, but copies files in file_list into folder_name.
- get_file_datetime(filepath)
- Parameters:
filepath – Object; the path to the file as a pathlib object.
- Returns:
A datetime (date stamp) for the file at the passed path.
- read_input_file(path, effects_log=None, usecols=None, index_col=None, skiprows=None, skip_blank_lines=True, reset_index=False)
- Parameters:
path – Path to the specified file.
effects_log – object; an object of the EffectsLog class.
usecols – List; the columns to use in the returned DataFrame.
index_col – int; the column to use as the index column of the returned DataFrame.
skiprows – int; the number of rows to skip when reading the file.
skip_blank_lines – bool; True will skip blank lines.
reset_index – Boolean; True resets index, False does not.
- Returns:
A DataFrame of the desired data from the passed input file.
- read_input_file_template_info(path, effects_log=None)
- Parameters:
path – Path to the specified file.
effects_log – object; an object of the EffectsLog class.
- Returns:
A DataFrame of the desired data from the passed input file.
- save_dict(settings, dict_to_save, save_path, row_header=None, stamp=None, index=False)
- Parameters:
settings – object; an object of the SetInputs class.
dict_to_save (dict) – the dictionary to be saved to CSV.
save_path – Path object; the path for saving the passed dict_to_save.
row_header – List; the column names to use as the row header for the preferred structure of the output file.
stamp – str; an identifier for inclusion in the filename, e.g., datetime stamp.
index – Boolean; True includes the index; False excludes the index.
- Returns:
Saves the passed dictionary to a CSV file.
- save_dict_return_df(dict_to_save, save_path, row_header=None, stamp=None, index=False)
- Parameters:
dict_to_save (dict) – the dictionary to be saved to CSV.
save_path – Path object; the path for saving the passed dict_to_save.
row_header – List; the column names to use as the row header for the preferred structure of the output file.
stamp – str; an identifier for inclusion in the filename, e.g., datetime stamp.
index – Boolean; True includes the index; False excludes the index.
- Returns:
Saves the passed dictionary to a CSV file and returns a DataFrame based on the passed dictionary.
- calc_rebound_effect(fuel_cpm_old, fuel_cpm_new, rebound_rate)
- Parameters:
fuel_cpm_old (numeric) – fuel cost per mile prior to a change, whether driven by fuel consumption or fuel price.
fuel_cpm_new (numeric) – fuel cost per mile after a change, whether driven by fuel consumption or fuel price.
rebound_rate (numeric) – this should be a negative value if fewer miles are driven upon higher costs per mile.
- Returns:
The rebound effect.
- calc_fuel_cost_per_mile(batch_settings, session_settings, calendar_year, onroad_direct_kwh_per_mile, onroad_direct_co2e_grams_per_mile, in_use_fuel_id)
- Parameters:
batch_settings – an instance of the BatchSettings class.
session_settings – an instance of the SessionSettings class.
calendar_year (int) – the calendar year needed for fuel prices.
onroad_direct_kwh_per_mile (float) – the onroad electricity consumption.
onroad_direct_co2e_grams_per_mile (float) – the onroad co2 grams per mile.
in_use_fuel_id (str) – a dict-like string providing fuel id information.
- Returns:
The fuel cost per mile in the given year for the given vehicle.
7.1.1.4.5. omega_effects.general.general_inputs_for_effects module
Routines to load General Inputs for Effects.
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows.
The data represent various general for use in effects calculations.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
general_inputs_for_effects
input_template_version:
0.1
- Sample Data Columns
item
value
notes
gal_per_bbl
42
gallons per barrel of oil
imported_oil_share
0.91
estimated oil import reduction as percent of total oil demand reduction
grams_per_uston
907185
Data Column Name and Description
- item:
The attribute name.
- value:
The attribute value
- notes:
Descriptive information regarding the attribute name and/or value.
- Data Row Name and Description:
- gal_per_bbl:
The number of gallons in a barrel of crude oil.
- e0_in_retail_gasoline:
The amount of petroleum-based gasoline in a gallon of retail gasoline where ‘e’ refers to ethanol.
- e0_energy_density_ratio:
The ratio of petroleum-based gasoline (e0) to crude oil energy density in British Thermal Units (BTU) per gallon.
- diesel_energy_density_ratio:
The ratio of diesel fuel to crude oil energy density in British Thermal Units (BTU) per gallon.
- grams_per_us_ton:
The number of grams in a US or short ton.
- grams_per_metric_ton:
The number of grams in a metric ton.
- years_in_consumer_view_1:
The number of years of a vehicle’s lifetime to include in the model year lifetime, or consumer view, calculations.
- years_in_consumer_view_2:
An additional number of years of a vehicle’s lifetime to include in the model year lifetime, or consumer view, calculations.
- include_powertrain_type_in_consumer_cost_view:
If 0 then powertrain_type (i.e., ICE/HEV/PHEV/BEV) is not included in the model year lifetime, or consumer view, sales weighting; if 1 then powertrain_type is included.
- social_discount_rates:
The discount rates to be used for discounting of costs and non-GHG pollutant benefits; the rate(s) should be entered in square brackets, separated by commas and entered as decimal values, i.e., 3% and 7% should be entered as [0.03, 0.07] .
- gwp_ch4:
The CO2 equivalent global warming potential for CH4. This is used for physical effects only as OMEGA does not apply a Social Cost of CO2e value.
- gwp_n2o:
The CO2 equivalent global warming potential for N2O. This is used for physical effects only as OMEGA does not apply a Social Cost of CO2e value.
CODE
- class GeneralInputsForEffects
Bases:
object
Loads and provides access to general input values for effects calculations.
- __init__()
- init_from_file(filepath, effects_log)
Initialize class data from input file.
- Parameters:
filepath – the Path object to the file.
effects_log – an instance of the EffectsLog class.
- Returns:
Nothing, but reads the appropriate input file.
- get_value(*attributes)
Get the attribute value for the given attribute.
- Parameters:
attributes (str) – the attribute(s) for which value(s) are sought.
- Returns:
The value of the given attribute.
7.1.1.4.6. omega_effects.general.input_validation module
OMEGA effects input validation module.
CODE
- validate_template_version_info(df, input_template_version, input_template_name=None, effects_log=None)
- Parameters:
df (DataFrame) – the DataFrame to validate.
input_template_version – the input template version.
input_template_name – the input template name.
effects_log – an instance of the EffectsLog class.
- Returns:
Checks input template header for necessary data.
- validate_template_column_names(filepath, df, column_names, effects_log=None)
- Parameters:
filepath – the Path object to the file.
df (DataFrame) – the DataFrame to validate.
column_names (list or set) – the column names that are necessary.
effects_log – an instance of the EffectsLog class.
- Returns:
Checks input tamplate for necessary data columns.
- get_module_name(filepath, effects_log)
Get input file template name. Can be used to identify the type of input file during simulation initialization when more than one type of input file may be provided (e.g. various GHG standards).
- Parameters:
filepath – the Path object to the file.
effects_log – an instance of the EffectsLog class.
- Returns:
The module name portion of the input file template name
7.1.2. Submodules
7.1.3. omega_effects.batch_settings module
OMEGA effects session settings.
INPUT FILE FORMAT
The file format consists of a one-row header followed by subsequent data rows.
The data represents OMEGA effects batch settings.
- File Type
comma-separated values (CSV)
- Sample Header
parameter
session_policy
value
full_path
notes
- Sample Data Rows
RUNTIME OPTIONS
Run ID
all
enter a run identifier (in value column) for your output folder name or blank for default (default is omega_effects)
Run Description
Save Path
all
C:omegaeffectsoutputs
enter full path, including drive id but do not include unique run identifiers
Save Input Files
all
FALSE
enter True to copy over input files or False to save space and not do so
Save Context Fuel Cost per Mile File
all
FALSE
enter True or False and note that these files can be large especially in CSV format
Save Vehicle-Level Safety Effects Files
all
FALSE
enter True or False and note that these files can be large especially in CSV format
Save Vehicle-Level Physical Effects Files
all
FALSE
enter True or False - these files can be large especially in CSV format
Save Vehicle-Level Cost Effects Files
all
FALSE
enter True or False - these files can be large especially in CSV format
Format for Vehicle-Level Output Files
all
csv
enter ‘csv’ for large Excel-readable files ‘parquet’ for compressed files usable in Pandas
Powertrain Costs FEV
all
TRUE
enter TRUE or FALSE (must be consistent with the compliance run)
BATCH SETTINGS
batch_folder
all
C:omegacompliance<batch folder>
Vehicles File Base Year
all
2022
this should be consistent with the OMEGA compliance run
Analysis Final Year
all
2055
this should be <= the value used in the OMEGA compliance run
Cost Accrual
all
end-of-year
Discount Values to Year
all
2027
Analysis Dollar Basis
all
2022
Context Name Liquid Fuel
all
AEO2023
Context Case Liquid Fuel
all
Reference case
Electricity Prices
all
IPM
enter ‘IPM’ or ‘AEO’
VMT Rebound Rate ICE
all
-0.1
VMT Rebound Rate BEV
all
0
SC-GHG in Net Benefits
all
global
enter ‘global’ or ‘domestic’ or ‘both’ (note that both global and domesitc benefits are calculated, this only impacts net benefits)
Maintenance Costs File
all
C:omegaeffectsinputsmaintenance_costs.csv
Repair Costs File
all
C:omegaeffectsinputs
- epair_costs.csv,
Refueling Costs File,all,,C:omegaeffectsinputs
- efueling_costs.csv,
General Inputs for Effects File,all,,C:omegaeffectsinputsgeneral_inputs_for_effects.csv, Criteria Cost Factors File,all,,C:omegaeffectsinputscriteria_cost_factors.csv, SCGHG Cost Factors File,all,,C:omegaeffectsinputsscghg_cost_factors.csv, Energy Security Cost Factors File,all,,C:omegaeffectsinputsenergy_security_cost_factors.csv, Congestion-Noise Cost Factors File,all,,C:omegaeffectsinputscongestion_and_noise_cost_factors.csv, Insurance and Taxes Cost Factors File,all,,C:omegaeffectsinputsinsurance_and_taxes_cost_factors.csv, Legacy Fleet File,all,,C:omegaeffectsinputslegacy_fleet.csv, CPI Price Deflators File,all,,C:omegaeffectsinputscpi_deflators_file.csv, EGU Data File,all,,C:omegaeffectsinputsegu_data.csv, Refinery Data File,all,,C:omegaeffectsinputs
- efinery_data.csv,
Safety Values File,all,,C:omegaeffectsinputssafety_values.csv, Fatality Rates File,all,,C:omegaeffectsinputs
- atality_rates.csv,
SESSION SETTINGS,,,, Session Name,context,<context session name>,, Context Stock and VMT File,context,,C:omegaeffectsinputscontext_stock_vmt.csv, Context Electricity Prices,context,,C:omegaeffectsinputselectricity_prices_aeo.csv, blank0,,,, Session Name,no_action,<no action session name>,, Session Vehicle Emission Rates File,no_action,,C:omegaeffectsinputs
- ehicle_emission_rates_no_gpf.csv,
Session Electricity Prices,no_action,,C:omegaeffectsinputselectricity_prices_ipm_no_action.csv, blank1,,,, Session Name,action_1,<action session name>,, Session Vehicle Emission Rates File,action_1,,C:omegaeffectsinputsvehicle_emission_rates_with_gpf.csv, Session Electricity Prices,action_1,,C:omegaeffectsinputselectricity_prices_ipm_action.csv,
Data Row Name and Description
RUNTIME OPTIONS
- Run ID:
A user defined run ID (optional; default=’omega_effects’)
- Run Description:
A user defined run description
- Save Path:
A full system path designation to which to save results
- Save Input Files:
True/False entry for whether to save the input files to the results folder
- Save Context Fuel Cost per Mile File:
True/False entry for whether to save the context fuel cost per mile file
- Save Vehicle-Level Safety Effects Files:
True/False entry for whether to save the vehicle-level safety effects file
- Save Vehicle-Level Physical Effects Files:
True/False entry for whether to save the vehicle-level physical effects file
- Save Vehicle-Level Cost Effects Files:
True/False entry for whether to save the vehicle-level cost effects file
- Format for Vehicle-Level Output Files:
‘csv’ or ‘parquet’; this entry must be ‘csv’ when running from the executable
- Powertrain Costs FEV:
True/False entry for whether to save the FEV developed powertrain costs
BATCH SETTINGS
- batch_folder:
Pathname of the OMEGA compliance batch folder on which to run effects
- Vehicles File Base Year:
The intended model year of the base year vehicles file, should be consistent with the OMEGA compliance run
- Analysis Final Year:
The final effects year, should be <= the value used in the OMEGA compliance run
- Cost Accrual:
The time of year when costs are assumed to accrue,
end-of-year
orbeginning-of-year
- Discount Values to Year:
The year to which all monetized values in the cost effects outputs will be discounted
- Analysis Dollar Basis:
The dollar valuation for all monetized values in the cost effects outputs, i.e., costs are expressed in “Dollar Basis” dollars
- Context Name Liquid Fuel:
Context name, e.g.
AEO2021
- Context Case Liquid Fuel:
Context case, e.g.,
Reference case
- Electricity Prices:
‘IPM’ or ‘AEO’; note that the context uses AEO since the context stock and VMT are from AEO
- VMT Rebound Rate ICE:
VMT rebound rate for internal combustion engines
- VMT Rebound Rate BEV:
VMT rebound rate for battery-electric vehicles
- SC-GHG in Net Benefits (str):
‘global’ or ‘domestic’ or ‘both’ (note that both global and domesitc benefits are calculated, if available, this only impacts net benefits)
- Maintenance Costs File (str):
The absolute path to the maintenance cost inputs file, loaded by
context.maintenance_cost.MaintenanceCost
- Repair Costs File (str):
The absolute path to the repair cost inputs file, loaded by
context.repair_cost.RepairCost
- Refueling Costs File (str):
The absolute path to the refueling cost inputs file, loaded by
context.refueling_cost.RefuelingCost
- General Inputs for Effects File (str):
The absolute path to the general inputs used for effects calculations, loaded by
general.general_inputs_for_effects.GeneralInputsForEffects
- Criteria Cost Factors File (str):
The absolute path to the criteria pollutant costs file, loaded by
effects.cost_factors_criteria.CostFactorsCriteria
- SCGHG Cost Factors File (str):
The absolute path to the social cost of carbon and carbon-equivalent pollutants file, loaded by
effects.cost_factors_scghg.CostFactorsSCGHG
- Energy Security Cost Factors File (str):
The absolute path to the energy security cost factors file, loaded by
effects.cost_factors_energysecurity.CostFactorsEnergySecurity
- Congestion-Noise Cost Factors File (str):
The absolute path to the congestion and noise cost factors file, loaded by
effects.cost_factors_congestion_noise.CostFactorsCongestionNoise
- Insurance and Taxes Cost Factors File (str):
The relative or absolute path to the insurance and taxes file, loaded by
consumer.cost_factors_insurance_and_taxes.InsuranceAndTaxes
- Legacy Fleet File (str):
The absolute path to the legacy fleet file, loaded by
effects.legacy_fleet.LegacyFleet
- CPI Price Deflators File (str):
The absolute path to the CPI price deflators file, loaded by
context.cpi_price_deflators.CPIPriceDeflators
- EGU Data File (str):
The absolute path to the EGU data file, loaded by
effects.egu_data.EGUdata
- Refinery Data File (str):
The absolute path to the Refinery data file, loaded by
effects.refinery_data.RefineryData
- Context Safety Values File (str):
The absolute path to the safety values file, loaded by
effects.safety_values.SafetyValues
- Context Fatality Rates File (str):
The absolute path to the fatality rates file, loaded by
effects.fatality_rates.FatalityRates
SESSION SETTINGS
- Session Name, context (str):
Context session name used in the OMEGA compliance run
- Context Stock and VMT File, context (str):
The absolute path to the context stock and VMT file, loaded by
context.context_stock_vmt.ContextStockVMT
- Context Electricity Prices, context (str):
The absolute path to the context electricity prices file, loaded by
context.electricity_prices.ElectricityPrices
- Session Name, no_action (str):
No Action session name used in the OMEGA compliance run
- Session Vehicle Emission Rates File, no_action (str):
The absolute path to the vehicle emission rates file, loaded by
effects.emission_rates_vehicles.EmissionRatesVehicles
- Session Electricity Prices, no_action (str):
The absolute path to the session electricity prices file, loaded by
context.electricity_prices.ElectricityPrices
- Session Name, action_1 (str):
An action session name used in the OMEGA compliance run
- Session Vehicle Emission Rates File, action_1 (str):
The absolute path to the vehicle emission rates file, loaded by
effects.emission_rates_vehicles.EmissionRatesVehicles
- Session Electricity Prices, action_1 (str):
The absolute path to the session electricity prices file, loaded by
context.electricity_prices.ElectricityPrices
CODE
- class BatchSettings
Bases:
object
Settings that apply to the whole batch of effects to run.
- __init__()
- init_from_file(filepath)
- Parameters:
filepath – the Path object to the file.
- get_attribute_value(key, attribute_name)
- Parameters:
key (tuple) – the applicable dictionary key
attribute_name (str) – the name of the parameter to read
- Returns:
The attribute value as set in the batch file. Path attributes will be returned as Path objects.
- get_batch_folder_and_name()
- Returns:
Nothing, but it sets the batch folder full path (as a string) and sets the batch name.
- get_run_id()
- Returns:
Nothing, but sets the run_id to the user entry, if provided, otherwise use default value.
- get_batch_settings(effects_log)
- Parameters:
effects_log – an instance fo the EffectsLog class.
- Returns:
Nothing, but it sets the class attributes included in the class init.
- init_batch_classes(effects_log)
- Parameters:
effects_log – an instance of the EffectsLog class.
- Returns:
Nothing, but it creates instances of classes needed for the batch.
- return_session_policy(session_name)
- Parameters:
session_name (str) – the name of a give session.
- Returns:
The session_policy (e.g., ‘no_action’, ‘action_1’) for the given session_name.
- static find_file(folder, file_id_string)
- Parameters:
folder – Path object of folder in which to find the file.
file_id_string (str) – The search string in the filename needed.
- Returns:
A Path object to the first file found that contains file_id_string in its name.
- get_runtime_options(effects_log)
- Parameters:
effects_log – object; an object of the ToolLog class.
- Returns:
creates a dictionary and other attributes specified in the class __init__.
- static path_of_batch_settings_csv()
- Returns:
An open-file dialog to select the batch settings file to use.
Note
This method allows for a user-interactive means of selecting the desired batch settings file.
- set_runtime_info()
7.1.4. omega_effects.omega_effects_main module
OMEGA effects main.
CODE
- main()
Main effects code.
7.1.5. omega_effects.session_settings module
OMEGA effects session settings.
CODE
- class SessionSettings
Bases:
object
OMEGA effects SessionSettings class.
- __init__()
- get_context_session_settings(batch_settings, effects_log)
This method is used to establish context session settings as specified in the BatchSettings class
- Parameters:
batch_settings – an instance of the BatchSettings class.
effects_log – an instance of the EffectsLog class.
- Returns:
Nothing, but it gets context session settings and creates instances of needed classes for the context.
- get_session_settings(batch_settings, session_num, effects_log)
This method is used to establish no action and action session settings as specified in the BatchSettings class
- Parameters:
batch_settings – an instance of the BatchSettings class.
session_num (int) – the session number.
effects_log – an instance of the EffectsLog class.
- Returns:
Nothing, but it gets no_action and action session settings and creates instances of needed classes for the session.
- init_context_classes(batch_settings, effects_log)
- Parameters:
batch_settings – an instance of the BatchSettings class.
effects_log – an instance of the EffectsLog class.
- Returns:
Nothing, but it creates instances of needed classes for the context.
- init_session_classes(batch_settings, session_name, effects_log)
- Parameters:
batch_settings – an instance of the BatchSettings class.
session_name (str) – the session name.
effects_log – an instance of the EffectsLog class.
- Returns:
Nothing, but it creates instances of needed classes for the session.
7.1.6. omega_effects.set_paths module
OMEGA file path handling.
CODE
- class SetPaths
Bases:
object
The SetPaths class sets the paths and run_id info used by the omega effects package.
- __init__()
- files_in_code_folder()
- Returns:
A generator object.
Note
This is just a generator that allows for copy/paste of tool code into a bundle of folders and files saved to the outputs folder.
- copy_code_to_destination()
- Returns:
Nothing, but copies contents of code folder to the destination.
Note
This is just a generator that allows for copy/paste of omega effects package code into a bundle of folders and files saved to the outputs folder.
- create_output_paths(path_name, batch_name, start_time_readable, run_id)
- Parameters:
path_name – save path set via batch settings file.
batch_name (str) – the batch name set via the runtime options input file.
start_time_readable (str) – the start time of the run, in text readable format.
run_id (str) – the run ID entered by the user or the default value if the user does not provide an ID.
- Returns:
Output paths into which to save outputs of the given run.
7.2. omega_gui package
Variables shared across GUI submodules
CODE
7.2.1. Submodules
7.2.2. omega_gui.omega_gui module
7.2.3. omega_gui.omega_gui_functions module
7.2.4. omega_gui.omega_gui_stylesheets module
This code contains stylesheets for the various graphical elements of the OMEGA GUI. The color scheme is set to the standard EPA publication Pantone palette.
- tab_stylesheet()
Loads the stylesheet for the tab area of the gui.
- Returns:
String containing stylesheet.
- background_stylesheet()
Loads the stylesheet for the main window of the gui.
- Returns:
String containing stylesheet.
- button_stylesheet()
Loads the stylesheet for buttons contained in the gui.
- Returns:
String containing stylesheet.
- development_stylesheet()
Loads the stylesheet for buttons contained in the gui.
- Returns:
String containing stylesheet.
- logo_button_stylesheet()
Loads the stylesheet for logo buttons contained in the gui.
- Returns:
String containing stylesheet.
- label_stylesheet()
Loads the stylesheet for labels contained in the gui.
- Returns:
String containing stylesheet.
- checkbox_stylesheet()
Loads the stylesheet for checkboxes contained in the gui.
- Returns:
String containing stylesheet.
- textbox_stylesheet()
Loads the stylesheet for textboxes contained in the gui.
- Returns:
String containing stylesheet.
- listbox_stylesheet()
Loads the stylesheet for listboxes contained in the gui.
- Returns:
String containing stylesheet.
- test1()
7.3. omega_model package
Top-level includes/definitions for the OMEGA model
Defines class OMEGASessionSettings which control an individual simulation session
CODE
- class OMEGASessionSettings
Bases:
OMEGABase
Define the settings required for a simulation session
- __init__()
Create an OMEGASessionSettings object with default settings used for testing and development.
The primary way to create an OMEGASessionSettings object is via the batch process.
See also
omega_batch.py, producer.vehicle_aggregation.py
- inputfile_metadata
stores information about input files such as filepath, filename and a unique checksum
- session_unique_name
used by the batch process to give each session within a batch a unique name
- timestamp_str
datetime string used to timestamp the session run
- start_time
used to track session duration
- end_time
used to track session duration
- output_folder_base
output folder base name e.g. ‘2024_01_18_09_32_54_BatchName_SessionName/’
- output_folder
path to the session output folder
- logfile_prefix
prefix of the session log file name, used in combination with the session unique name
- logfilename
stores the full filepathname of the session log file
- session_is_reference
=
True
if this session is the reference (context) session
- auto_close_figures
auto close postproc figures if
True
- save_preliminary_outputs
retains preliminary (i.e. first pass) outputs if
True
- omega_model_path
absolute path to the
omega_model
directory
- analysis_initial_year
stores the analysis initial year, e.g. vehicle base year + 1
- consolidate_manufacturers
run compliance model with a single, consolidated, manufacturer instead of individual manufacturers
- manufacturer_gigawatthour_data
stores first pass total battery GWh consumption by manufacturer for use in limiting second pass GWh
- generate_context_calibration_files
if
True
(i.e.session_is_reference
) generate context session outputs for use by non-context sessions
- context_new_vehicle_generalized_costs_file
filepathname of the context session new vehicle generalized costs
filepathname of the context session sales share calibration file, if any
- vehicles_df
used to store base year vehicle data as a result of vehicle aggregation
- analysis_final_year
must be >=
analysis_initial_year
- analysis_dollar_basis
the ‘dollar year’ of analysis ouputs, for comparing costs adjusted for inflation/deflation
- context_id
id of the context data used for the context session, e.g. ‘AEO2021’
- context_case_id
id of the context sub-case, e.g. ‘Reference case’, ‘High oil price’, etc
- credit_market_efficiency
1.0 = ‘perfect trading’, less than 1.0 implies less than perfect trading of GHG compliance credits, 0.0 implies no trading and all manufacturers must meet their standards using only averaging and banking
- context_fuel_prices_file
path the context fuel prices file, used by
context.fuel_prices
- context_electricity_prices_file
path to the context electricity prices file, used by the user-definable
ElectricityPrices
class
- context_new_vehicle_market_file
path to the context new vehicle market file, used by the user-definable
NewVehicleMarket
class
- manufacturers_file
path to the manufacturers file, used by
producer.manufacturers
- market_classes_file
path the market class definition file, used by the user-definable
MarketClass
class
- new_vehicle_price_elasticity_of_demand
indicates change in sales v. change in price at the industry level, used to project action session total sales
- onroad_fuels_file
path to the onroad fuels file, used by
context.onroad_fuels
- onroad_vehicle_calculations_file
path the onroad vehicle calculations file, used by the
Vehicle
class
- onroad_vmt_file
path the onroad annual vehicle miles travelled file, used by the user-definable
OnroadVMT
class
- consumer_pricing_multiplier_max
maximum market class price multiplier during producer cross-subsidy
- consumer_pricing_multiplier_min
minimum market class price multiplier during producer cross-subsidy (ideally should be
1/consumer_pricing_multiplier_max
)
- producer_generalized_cost_file
path to the producer generalized cost file, used by the user-definable
ProducerGeneralizedCost
class
- production_constraints_file
path to the production constraings file, used by
context.production_constraints
path to the sales share file, used by the user-definable
SalesShare
class
- vehicle_price_modifications_file
path the vehicle price modifications (e.g. ‘incentives’) file, used by
context.price_modifications
- vehicle_reregistration_file
path to the vehicle re-registration file, used by the user-definable
Reregistration
class
- ice_vehicle_simulation_results_file
path the ICE vehicles simulation results file, used by the user-definable
CostCloud
class
- bev_vehicle_simulation_results_file
path the BEV vehicles simulation results file, used by the user-definable
CostCloud
class
- phev_vehicle_simulation_results_file
path the PHEV vehicles simulation results file, used by the user-definable
CostCloud
class
- vehicles_file
path the base year vehicles file, used by
producer.vehicle_aggregation
- powertrain_cost_input_file
path to the power train costs file, used by the user-definable
PowertrainCost
class
- glider_cost_input_file
path the glider cost file, used by
context.glider_cost
- body_styles_file
path the body styles file, used by
context.body_styles
- mass_scaling_file
path the mass scaling file, used by
context.mass_scaling
- workfactor_definition_file
path to the workfactor definition file, used by
policy.workfactor_definition
- session_name
session name string
- drive_cycle_weights_file
path to drive cycle weights file, used by
policy.drive_cycle_weights
- drive_cycle_ballast_file
path to drive cycle ballast file, used by
policy.drive_cycle_ballast
- drive_cycles_file
path to drive cycles file, used by
policy.drive_cycles
- ghg_credit_params_file
path to GHG credit params file, used by
policy.credit_banking
- ghg_credits_file
path to GHG credits file, used by
policy.credit_banking
- policy_targets_file
path to policy target definitions file, used by user-definable
VehicleTargets
class
- offcycle_credits_file
path to offcycle credits file, used by user-definable
OffCycleCredits
class
- fuel_upstream_methods_file
path to upstream methods file, used by
policy.upstream_methods
- utility_factor_methods_file
path to utility factor methods file, used by
policy.utility_factors
- policy_fuels_file
path to policy fuels file, used by
policy.policy_fuels
- production_multipliers_file
path to production multipliers file, used by
policy.incentives
- policy_reg_classes_file
path to policy reg classes file, used by user-definable
RegulatoryClasses
class
path to required sales share file, used by
policy.required_sales_share
- ip_deflators_file
path to implicit price deflators file, used by
context.ip_deflators
- use_prerun_context_outputs
if
True
then use context session outputs from a previously run context session
- prerun_context_folder
path to the previously run context session, if
use_prerun_context_outputs
isTrue
- battery_GWh_limit_years
used in combination with
battery_GWh_limit
to create industry-level battery production capacity limits year over year
- battery_GWh_limit
used in combination with
battery_GWh_limit_years
to create industry-level battery production capacity limits year over year
- producer_price_modification_scaler
if non-zero then some scalar portion of vehicle incentives (price modifications) are incorporated into the producer vehicle generalized cost
- producer_footprint_wtp
producer’s estimate of consumer willingness to pay for increases in vehicle footprint, used in producer vehicle generalized cost
- footprint_min_scaler
vehicle footprint minimum scaler in producer footprint sweep as part of composite vehicle cost cloud generation
- footprint_max_scaler
vehicle footprint maximum scaler in producer footprint sweep as part of composite vehicle cost cloud generation
- redesign_interval_gain_years
used in combination with
redesign_interval_gain
to allow modification of vehicle redesign cadence if desired
- redesign_interval_gain
used in combination with
redesign_interval_gain_years
to allow modification of vehicle redesign cadence if desired
- non_context_session_process_scaler
used to modify the number of processes used by non-context sessions when multiprocessing, (e.g. 2 = use 1/2 the default number of processes)
if
True
then consumer share response is ignored. Used for development, troubleshooting, or quicker runtime during testing
- producer_compliance_search_multipoint
if
True
then the producer compliance search will simultaneously approach compliance from points above and below compliance (if possible)
- powertrain_cost_with_ira
if
True
then Inflation Reduction Act incentives will apply to powertrain costs
- powertrain_cost_with_gpf
if
True
then gasoline particulate filter costs will apply to powertrain costs
- powertrain_cost_tracker
if
True
then detailed powertrain cost outputs will be generated
- base_year_min_sales
minimum base year vehicles sales threshhold to consider when reading the base year vehicles file (e.g. ignore low-volume vehicles)
- phev_range_mi
target PHEV charge-depleting range, miles
- bev_of_ice_rlhp60_scaler
scaler for BEV roadload horsepower at 60 MPH (BEVs more aerodynamic than their ICE equivalent if scaler < 1.0)
- no_backsliding
if
True
then ICE vehicles must maintain or improve CO2e g/mi across redesign cycles
used to define year over year share of BEVs with Nickel Manganese Cobalt battery type
used to define year over year share of PHEVs with Nickel Manganese Cobalt battery type
used to define year over year share of HEVs with Nickel Manganese Cobalt battery type
- battery_cost_constant_thru
hold battery costs constant through this year
- producer_market_category_ramp_limit
used to constrain producer sales shift between market classes (e.g ICE/BEV). 0.2 => five years to fully switch from one class to another
- producer_strategic_compliance_buffer_years
used in combination with
producer_strategic_compliance_buffer
to allow manually banking (or burning) GHG credits year over year
- producer_strategic_compliance_buffer
used in combination with
producer_strategic_compliance_buffer_years
to allow manually banking (or burning) GHG credits year over year
- relax_second_pass_GWh
if
True
then second pass battery GWh production may exceed first pass production
- vehicles_file_base_year_offset
added to the base year vehicles file model year and prior redesign year
- bev_range_mi
target BEV charge-depleting range, miles
- bev_mdv_van_range_mi
target medium-duty van charge-depleting range, miles
- kwh_per_mile_scale_years
used in combination with
kwh_per_mile_scale
to scale BEV kWh/mile consumption values year over year, e.g. simulate improvements over time relative to the original simulation results
- kwh_per_mile_scale
used in combination with
kwh_per_mile_scale_years
to scale BEV kWh/mile consumption values year over year, e.g. simulate improvements over time relative to the original simulation results
- rlhp20_min_scaler
minimum roadload horsepower at 20 MPH scaler when sweeping RLHP20
- rlhp20_max_scaler
maximum roadload horsepower at 20 MPH scaler when sweeping RLHP20
- rlhp60_min_scaler
minimum roadload horsepower at 60 MPH scaler when sweeping RLHP60
- rlhp60_max_scaler
maximum roadload horsepower at 60 MPH scaler when sweeping RLHP60
- allow_ice_of_bev
if
True
then base year BEVs will have ICE-equivalent alternative powertrain vehicles available starting at first redesign
- phev_battery_kwh
'RSE'
=> use RSE,None
=> use range calc, otherwise use scalar value to size PHEV battery capacity
- force_two_pass
can be used to force two pass (consolidated and non-consolidated compliance passes) as desired
- include_manufacturers_list
'all'
to include all base year vehicle manufacturers, else list of manufacturers to include, e.g.['Ford', 'Honda', ...]
- exclude_manufacturers_list
'none'
to include all base year vehicle manufacturers, else list of manufacturers to exclude, e.g.['Ferrari', 'Bugatti', ...]
- cost_curve_frontier_affinity_factor
used in calculation cloud frontiers, lower values generate a more ‘approximate’ fit to the cloud and a lower number of points on the frontier, higher values generate a tighter fit and generally more points
- slice_tech_combo_cloud_tables
if
True
then only save producer search production options data within +- 20% of the target Mg, used in combination withlog_producer_compliance_search_years
andverbose_log_modules
- verbose
if
True
then enable optional console outputs
- iterate_producer_consumer
enable producer-consumer cross subsidy iteration when
True
- second_pass_production_constraints
if
True
then apply industry-level production constraints on the second pass
- producer_voluntary_overcompliance
enable producer voluntary overcompliance if
True
, experimental
- flat_context
if
True
then all context values are determined byflat_context_year
instead of model year, for troubleshooting
- flat_context_year
used in combination with
flat_context
to set constant context values
- run_profiler
run profiler if
True
- multiprocessing
enables multiprocessing if
True
nominal number of market share options considered per producer compliance search iteration
- producer_num_tech_options_per_ice_vehicle
nominal number of tech options per ICE vehicle considered per producer compliance search iteration
- producer_num_tech_options_per_bev_vehicle
nominal number of tech options per BEV vehicle considered per producer compliance search iteration
the minimum share range used during producer compliance search iteration
- producer_compliance_search_convergence_factor
producer search share range =
producer_compliance_search_convergence_factor ** iteration_num
- producer_compliance_search_tolerance
used to determine if producer compliance search as found an acceptable solution, relative to 1.0 being perfect compliance
- producer_voluntary_overcompliance_min_benefit_frac
minimum benefit of voluntary overcompliance, as a fraction of compliance cost, experimental
- producer_voluntary_overcompliance_min_strategic_compliance_ratio
determines the maxinum voluntary overcompliance to consider, experimental
- producer_consumer_max_iterations
determines the maximum number of producer-consumer cross subsidy iterations to consider
- producer_consumer_convergence_tolerance
the threshhold for determining producer-consumer share convergence, absolute market share
- consumer_pricing_num_options
the number of cross-subsidy pricing options to consider per cross-subsidy iteration per market class
- producer_cross_subsidy_price_tolerance
the threshhold for determining producer-consumer price convergence, relative to 1.0 being perfect price convergence
- verbose_log_modules
used to enable verbose log file outputs for various modules
- verbose_console_modules
used to enable verbose console outputs for various modules
- verbose_postproc
used to control verbose postproc outputs
- canary_byvid
canary base year vehicle ID, for development or troubleshooting
- log_vehicle_cloud_years
=
'all'
or list of years to log, empty list to disable logging
- log_producer_compliance_search_years
=
'all'
or list of years to log, empty list to disable logging
- log_consumer_iteration_years
=
'all'
or list of years to log, empty list to disable logging
- log_producer_decision_and_response_years
=
'all'
or list of years to log, empty list to disable logging
- plot_and_log_vehicles
list of vehicles to plot in log_producer_compliance_search_years, by namem e.g.
['ICE Large Van truck minivan 4WD']
- RegulatoryClasses
reference to user-definable RegulatoryClasses class
- VehicleTargets
reference to user-definable VehicleTargets class
- OffCycleCredits
reference to user-definable OffCycleCredits class
- Reregistration
reference to user-definable Reregistration class
- OnroadVMT
reference to user-definable OnroadVMT class
reference to user-definable SalesShare class
- ProducerGeneralizedCost
reference to user-definable ProducerGeneralizedCost class
- MarketClass
reference to user-definable MarketClass class
- CostCloud
reference to user-definable CostCloud class
- PowertrainCost
reference to user-definable PowertrainCost class
- ElectricityPrices
reference to user-definable ElectricityPrices class
- notification_destination
for optional text notifications, see
common.omega_functions.send_text()
- notification_email
for optional text notifications, see
common.omega_functions.send_text()
- notification_password
for optional text notifications, see
common.omega_functions.send_text()
7.3.1. Subpackages
7.3.1.1. omega_model.common package
OMEGA common functionality subpackage.
CODE
- FALSE = 0
use for boolean values as numeric
- TRUE = 1
use for boolean values as numeric
7.3.1.1.1. Submodules
7.3.1.1.2. omega_model.common.file_io module
Handy file system routines for general use
Generally, user-friendly wrappers for functionality provided by the os
and shutil
packages.
CODE
- get_user_home()
Get user home directory, works cross-platform
- Returns:
User home directory as a string
- move_folder_contents(srcfolder, dstfolder)
Move files from the srcfolder to the dstfolder and delete the srcfolder
- Parameters:
srcfolder (str) – source folder path
dstfolder (str) – destination folder path
- delete_folder(dstfolder)
Delete the dstfolder
delete_folder('C:\Users\Temp')
- Parameters:
dstfolder – Path the folder to delete
- validate_folder(dstfolder)
Verify the existence of dstfolder and try to create it if doesn’t exist
validate_folder('C:\Users\Temp')
- Parameters:
dstfolder – Path the folder to validate/create
Attention
Exits app on failure
- file_exists(filename)
Verify the existence of filename
- Parameters:
filename – File pathname of the file to validate
- Returns:
True
if file is accessible (exists)
- validate_file(filename)
Verify the existence of filename
- Parameters:
filename – File pathname of the file to validate
Attention
Exits app on failure
- get_filepath(filename)
Returns path to file, e.g. /somepath/somefile.txt -> /somepath
- Parameters:
filename – file name, including path to file as required
- Returns:
file path, not including the file name
- get_filepathname(filename)
Returns file name without extension, including path, e.g. /somepath/somefile.txt -> /somepath/somefile
- Parameters:
filename – file name, including path to file as required
- Returns:
file name without extension, including path
- get_absolute_path(filename)
Get the full, absolute path of filename
- Parameters:
filename (str) – name of file available on the current path
- Returns:
The full, absolute path of filename
- get_basename(pathname)
Return the base name of pathname path. This is the second element of the pair returned by passing path to the function split(). Note that the result of this function is different from the Unix basename program; where basename for ‘/foo/bar/’ returns ‘bar’, the basename() function returns an empty string (‘’).
- Parameters:
pathname (str) – the path to get the basename of
- Returns:
The base name of pathname path.
- get_filename(filename)
Returns file name without extension, e.g. /somepath/somefile.txt -> somefile
- Parameters:
filename – file name, including path to file as required
- Returns:
file name without extension
- get_filenameext(filename)
Returns file name including extension, e.g. /somepath/somefile.txt -> somefile.txt
- Parameters:
filename – file name, including extension, including path to file as required
- Returns:
file name including extension
- get_parent_foldername(filepathnameext)
Returns the parent folder of the given file e.g. /apath/somepath/somefile.txt -> somepath
- Parameters:
filepathnameext – file name, including extension and path to file
- Returns:
parent folder of the given file
- network_copyfile(remote_path, srcfile)
Copy srcfile to remote_path
- Parameters:
remote_path – Path to file destination
srcfile – source file name, including extension and path to file
- relocate_file(remote_path, local_filename)
Move local_filename out to remote_path and return the filename in that remote context
- Parameters:
remote_path – Path to file destination
local_filename – local source file name, including extension and path to file as required
- sysprint(msg)
Performs ECHO command of str in CMD window
- Parameters:
msg – string to echo
7.3.1.1.3. omega_model.common.input_validation module
Routines to validate input file formats and/or values.
Used during the initialization process.
CODE
- get_template_columns(filename)
- Parameters:
filename (str) – name of the file from which to get the input columns
Returns:
- get_template_name(filename)
Get input file template name. Can be used to identify the type of input file during simulation initialization when more than one type of input file may be provided (e.g. various GHG standards).
- Parameters:
filename (str) – name of the file from which to get the input template name
- Returns:
The input file template name
- validate_template_version_info(filename, input_template_name, input_template_version, verbose=False)
Reads the template version infor from an input file and validates the template name and version number.
- Parameters:
filename (str) – name of the input file to validate
input_template_name (str) – target template name
input_template_version (numeric) – target template version
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template errors, else empty list on success
- validate_template_column_names(filename, input_template_columns, columns, verbose=False)
Validate input columns against target template columns.
- Parameters:
filename (str) – name of the input file to validate
input_template_columns ([strs]) – list of target template column names
columns ([strs]) – list of column names to validate
verbose – enable additional console and logfile output if True
- Returns:
List of column name errors, else empty list on success
- validate_dataframe_columns(df, validation_dict, error_source=None, header_lines=2)
Validate dataframe column(s) against allowed values
- Parameters:
df (DataFrame) – pandas dataframe containing data to validate
validation_dict (dict) – dict of one or more column name / allowed value pairs
error_source (str) – typically the name of the file containing the error
header_lines (int) – header_lines (int): number of header lines in the input file, offset used to calculate the row number of the error
- Returns:
Empty list on success or list of errors on failure
7.3.1.1.4. omega_model.common.omega_dispy module
Routines and data structures to support multi-processor / multi-machine OMEGA simulations via the dispy package.
Generally speaking, running with dispy
is a bit of an advanced topic, and is not required in order to run a
multi-session batch. When getting started with dispy
it’s best to get started on a single machine before
working up to a multi-machine setup.
To run using dispy
, each machine must have a running instance of dispynode
, typically launched from a command
line script. Also, each machine must have access to a shared folder where the source files for each
run will be staged.
Example
#! /bin/zsh
PYTHONPATH="/Users/omega_user/Code/GitHub/USEPA_OMEGA2/venv3.8/bin"
DISPYPATH="/Users/omega_user/Code/GitHub/USEPA_OMEGA2/venv3.8/lib/python3.8/site-packages/dispy"
$PYTHONPATH/python3 $DISPYPATH/dispynode.py --clean --cpus=8 --client_shutdown --ping_interval=15 --daemon --zombie_interval=5
Since this is an advanced use case, EPA can provide limited support for its use.
CODE
- sysprint(message)
Echo/print a message to the system standard output (i.e. the console)
- Parameters:
message (str) – the message to print
- dispy_node_setup()
Prints a short hello message to the console, verifying that the dispynode is up and running (used during ping mode).
- restart_job(job)
Restart an abandonded or failed DispyJob.
- Parameters:
job (DispyJob) – the job to restart
- job_cb(job)
Job callback function. Gets called for: (DispyJob.Finished, DispyJob.Terminated, DispyJob.Abandoned)
- Parameters:
job (DispyJob) – the job associated with the callback
- status_cb(status, node, job)
Cluster status callback function. It is called by
dispy
(client) to indicate node / job status changes.- Parameters:
status – job status (e.g. dispy.DispyJob.Created, dispy.DispyJob.Running, etc)
node (DispyNode, IP address, or host name) – the node associated with the cluster
job (DispyJob) – the job associated with the callback
- dispy_run_session(batch_name, network_batch_path_root, batch_file, session_num, session_name, retry_count=0)
Runs an OMEGA simulation session on a DispyNode.
- Parameters:
batch_name (str) – the name of the batch
network_batch_path_root (str) – name/path to a shared folder where the source files will be staged
batch_file (str) – path to the batch file being run
session_num (int) – the session number to be run
session_name (str) – the name of the session being run
retry_count (int) – retry count of the session
- class DispyCluster(options)
Bases:
object
Implements an object to run OMEGA sessions on dispy nodes.
- __init__(options)
Create a DispyCluster object with the provided batch options.
- Parameters:
options (OMEGABatchOptions) – batch options, see
omega_batch.py
for more info
- static get_ip_address()
Attempt to get “local” IP address(es)
Example:
>>> socket.gethostbyname_ex(socket.gethostname()) ('mac-mini.local', [], ['127.0.0.1', '192.168.1.20'])
Returns: list of local IP address(es)
- find_nodes()
Look for available DispyNodes and update
self.found_node_list
with a list of the discovered nodes.
- submit_sessions(batch, batch_name, batch_path, batch_file, session_list)
Submit sessions to a DispyCluster. Called from
omega_batch.py
.- Parameters:
batch (OMEGABatchObject) – the batch object, see
omega_batch.py
batch_name (str) – the name of the batch, e.g. ‘2021_06_29_13_34_44_multiple_session_batch’
batch_path (str) – the filesystem path to the bundle folder for the batch, e.g. ‘/Users/omega_user/bundle’
batch_file (str) – the filesystem path to the batch file to run (minus the ‘.csv’ extension), e.g. ‘/Users/omega_user/bundle/2021_06_29_13_34_44_batch/2021_06_29_13_34_44_batch’
session_list (iterable) – a list or range of one or more sessions to run, by session number, e.g. range(1, 3)
7.3.1.1.5. omega_model.common.omega_eval module
Code to handle runtime compilation of eval statemetns.
CODE
- class Eval
Bases:
OMEGABase
Class to cache compiled eval statements and return their values.
- classmethod eval(source, global_vars=None, local_vars=None)
Like python eval() except on first use it compiles the statement and caches the code for future use.
The source must be a string representing a Python expression. The globals must be a dictionary and locals can be any mapping, defaulting to the current globals and locals. If only globals is given, locals defaults to it.
- Parameters:
source (str) – the statement to be evaluated
global_vars (dict) – dict of global variables
local_vars (mapping) – dict/mapping of local variables
- Returns:
The value of the evaluated expression
7.3.1.1.6. omega_model.common.omega_functions module
Various functions that may be used throughout OMEGA.
CODE
- get_ip_address()
Attempt to get “local” IP address(es)
Example:
>>> socket.gethostbyname_ex(socket.gethostname()) ('mac-mini.local', [], ['127.0.0.1', '192.168.1.20'])
Returns: list of local IP address(es)
- dataframe_to_numeric(df)
Convert dataframe columns to numeric (i.e. non-object dtypes) if possible.
- Parameters:
df (DataFrame) – the dataframe to convert to numeric
- Returns:
df with numeric columns where possible
- series_to_numeric(ser)
Convert series entries to numeric (i.e. non-object dtypes) if possible.
- Parameters:
ser (Series) – the series to convert to numeric
- Returns:
ser with numeric columns where possible
- sales_weight_average_dataframe(df)
Numeric columns are sales-weighted-averaged except for ‘model_year’ and columns containing ‘sales’, which is the weighting factor. Non-numeric columns have unique values joined by ‘:’
- Parameters:
df (DataFrame) – the dataframe to sales-weight
- Returns:
DataFrame with sales-weighted-average for numeric columns
- plot_frontier(cost_cloud, cost_curve_name, frontier_df, x_key, y_key)
Plot a cloud and its frontier. Saves plot to
o2.options.output_folder
.- Parameters:
cost_cloud (DataFrame) – set of points to plot
cost_curve_name (str) – name of plot
frontier_df (DataFrame) – set of points on the frontier
x_key (str) – column name of x-value
y_key (str) – columns name of y-value
Example
# from calc_cost_curve() in vehicles.py plot_frontier(self.cost_cloud, '', cost_curve, 'cert_co2e_grams_per_mile', 'new_vehicle_mfr_cost_dollars')
- calc_frontier(cloud, x_key, y_key, allow_upslope=False, invert_x_axis=True)
Calculate the frontier of a cloud.
- Parameters:
cloud (DataFrame) – a set of points to find the frontier of
x_key (str) – name of the column holding x-axis data
y_key (str) – name of the column holding y-axis data
allow_upslope (bool) – allow U-shaped frontier if
True
invert_x_axis (bool) – invert x-axis if
True
- Returns:
DataFrame containing the frontier points
- get_idxmin(cloud, min_frontier_factor, x_key)
Return the index of the minimum value of the
cloud
frontier_factor
.- Parameters:
cloud (DataFrame) – a set of points to find the frontier of
min_frontier_factor (float) – the minimum value of the frontier_factor
x_key (str) –
cloud
column name
- Returns:
The index of the minimum value of the
cloud
frontier_factor
.
- calc_frontier_factor_up(cloud, prior_x, prior_y, x_key, y_key)
Calculate the frontier factor for an up-sloping cloud of points.
- Parameters:
cloud (DataFrame) – a set of points to find the frontier of
prior_x (float) – x-axis value of prior frontier point
prior_y (float) – y-axis value of prior frontier point
x_key (str) – name of the column holding x-axis data
y_key (str) – name of the column holding y-axis data
- Returns:
Nothing, calculates
frontier_factor
column ofcloud
.
- calc_frontier_factor_down(cloud, prior_x, prior_y, x_key, y_key)
Calculate the frontier factor for an down-sloping cloud of points.
- Parameters:
cloud (DataFrame) – a set of points to find the frontier of
prior_x (float) – x-axis value of prior frontier point
prior_y (float) – y-axis value of prior frontier point
x_key (str) – name of the column holding x-axis data
y_key (str) – name of the column holding y-axis data
- Returns:
Nothing, calculates
frontier_factor
column ofcloud
.
- cull_cloud(cloud, prior_x, x_key)
Remove points from a dataframe where the given column (
x_key
) is above a certain value (prior_x
).- Parameters:
cloud (dataframe) – the dataframe to cull
prior_x (float) – the threshold value
x_key (str) – cloud column name
- Returns:
cloud
with culled points removed
- sum_dict(dict_in, include=None, exclude=None)
Add up all terms in a dict given the
include
andexclude
constraints.- Parameters:
dict_in (numeric dict_like) – the object with elements to sum
include (str) – include term in sum if
include
in dict keyexclude (str) – exclude term from some if
exclude
in dict key
- Returns:
Sum of terms in
dict_in
given the include and exclude constraints.
- print_keys(dict_in, include=None, exclude=None, values=True)
Print some or all keys (and optionally values) in a dict-like object
- Parameters:
dict_in (dict-like) – the object with keys to print
include (str) – a substring that must be present, if provided
exclude (str) – a substring that must not be present, if provided
values (bool) – print values if
True
- print_dict(dict_in, num_tabs=0, to_string=False)
Attempt to printy-print a dictionary to the Python console.
- Parameters:
dict_in (dict) – dictionary to print
num_tabs (int) – optional argument, used to indent subsequent layers of the dictionary
to_string (Bool) – if True then result will be returned as a printable string, instead of printed to the console
- Returns:
print_dict string if to_string==True
- print_list(list_in)
Print the given list, one line per item
- Parameters:
list_in (list) – the list to print
- linspace(min_val, max_val, num_values)
Create a list of num_values evenly spaced values between min and max. Based on
Matlab
linspace command.- Parameters:
min_val (numeric) – the minimum value
max_val (numeric) – the maximum value
num_values (int) – the total number of values to return
- Returns:
A list of evenly spaced values between min and max
- partition(column_names, num_levels=5, min_constraints=None, max_constraints=None, verbose=False)
Generate a dataframe with columns from
column_names
, whose rows sum to 1.0 across the columns, following the given constraints- Parameters:
column_names (list | int) – list of column names or number of columns
num_levels (int) – number of values in the column with the lowest span (min value minus max value)
min_constraints (int | dict) – a scalar value or dict of minimum value constraints with column names as keys
max_constraints (int | dict) – a scalar value or dict of maximum value constraints with column names as keys
verbose (bool) – if
True
then the resulting partition will be printed
- Returns:
A dataframe of the resulting partition
Example
p = partition_x(['BEV','ICE','PHEV'], min_constraints={'BEV':0.1}, max_constraints={'BEV':0.2, 'PHEV':0.25}, num_levels=5, verbose=True)
- unique(vector)
Return unique values in a list of values, in order of appearance.
- Parameters:
vector ([numeric]) – list of values
- Returns:
List of unique values, in order of appearance
- distribute_by_attribute(obj_list, value, weight_by, distribute_to)
Used to take a value and distribute it to source values by a weight factor. Used to assign composite attributes to source objects, e.g. composite vehicle sales to source vehicle sales, etc. The weight factor is normalized by the sum of the object weights. For example, if there were two objects, one with a 0.2 weight and one with a 0.1 weight, the first object would get 2/3 of the value and the second would get 1/3 of the value.
- Parameters:
obj_list ([objs]) – list of objects to distribute to
value (numeric) – the value to to distribute
weight_by (str) – the name of the object attribute to use as a weight factor
distribute_to (str) – the name of the object attribute to distribute to
- weighted_value(objects, weight_attribute, attribute, attribute_args=None)
Calculate a weighted value from values taken from a set of objects. The contribution of each object is normalized by the sum of the object weight attribute values.
- Parameters:
objects ([objs]) – list of source objects
weight_attribute (str) – the name of the object attribute to weight by (e.g. ‘sales’)
attribute (str) – the name of the attribute to calculate the weighted value of, e.g. vehicle CO2e g/mi, etc
attribute_args – arguments to the attribute, if the attribute is a method or function, e.g. calendar_year
- Returns:
The weighted value
- cartesian_prod(left_df, right_df)
Calculate cartesian product of the dataframe rows.
- Parameters:
left_df (DataFrame) – ‘left’ dataframe
right_df (DataFrame) – ‘right’ dataframe
- Returns:
Cartesian product of the dataframe rows (the combination of every row in the left dataframe with every row in the right dataframe).
Generate a partition of share values in the neighborhood of an initial set of share values.
See also
compliance_strategy.create_compliance_options()
- Parameters:
columns ([strs]) – list of values that represent shares in combo
combo (Series) – Series that contains the initial set of share values
half_range_frac (float) – search “radius” [0..1], half the search range
num_steps (int) – number of values to divide the search range into
min_constraints (dict) – minimum partition constraints [0..1], by column name
max_constraints (dict) – maximum partition constraints [0..1], by column name
verbose (bool) – if
True
then partition dataframe is printed to the console
- Returns:
DataFrame of partion values.
Example
>>>columns ['producer_share_frac_non_hauling.BEV', 'producer_share_frac_non_hauling.ICE'] >>>combos veh_non_hauling.BEV.car_co2e_gpmi ... slope 1510 15.91862 ... 0 2135 15.91862 ... 0 [2 rows x 79 columns] >>>half_range_frac 0.33 >>>num_steps 5 >>>min_constraints {'producer_share_frac_non_hauling.BEV': 0.001, 'producer_share_frac_non_hauling.ICE': 0} >>>max_constraints {'producer_share_frac_non_hauling.BEV': 1, 'producer_share_frac_non_hauling.ICE': 1} Returns: producer_share_frac_non_hauling.BEV producer_share_frac_non_hauling.ICE 0 0.0010 0.9990 1 0.0835 0.9165 2 0.1660 0.8340 3 0.2485 0.7515 4 0.3310 0.6690 5 0.0010 0.9990
Note
In the example above, there appear to be repeated rows, however the values are unique in floating-point terms, e.g. 0.00100000000000000002 versus 0.00100000000000000089
- ASTM_round(var, precision=0)
Rounds numbers as defined in ISO / IEC / IEEE 60559
- Parameters:
var (float, Series) – number to be rounded, scalar or pandas Series
precision (int) – number of decimal places in result
- Returns:
var rounded using ASTM method with precision decimal places in result
- calc_roadload_hp(A_LBSF, B_LBSF, C_LBSF, MPH)
Calculate roadload horsepower from ABC coefficients and vehicle speed (MPH)
- Parameters:
A_LBSF (float) – “A” coefficient, lbs
B_LBSF (float) – “B” coefficient, lbs/mph
C_LBSF (float) – “C” coefficient, lbs/mph^2
MPH (float(s)) – scalar float, numpy array or Series of vehicle speed(s), mph
- Returns:
Roadload horsepower at the given vehicle speed
- send_text(dest, message, email, password)
SMS Gateways for each Carrier AT&T: [number]@txt.att.net Sprint: [number]@messaging.sprintpcs.com or [number]@pm.sprint.com T-Mobile: [number]@tmomail.net Verizon: [number]@vtext.com Boost Mobile: [number]@myboostmobile.com Cricket: [number]@sms.mycricket.com Metro PCS: [number]@mymetropcs.com Tracfone: [number]@mmst5.tracfone.com U.S. Cellular: [number]@email.uscc.net Virgin Mobile: [number]@vmobl.com
- Parameters:
dest (str) – e.g. ‘8005552323@myboostmobile.com’
message (str) – the message to send
email (str) – the email address of the email server to use, e.g. ‘my_email@gmail.com’
password (str) – the password for the email account, recommend setting up an app-specific password
- deep_getsizeof(o, ids=None)
Find the memory footprint of a Python object in bytes
This is a recursive function that drills down a Python object graph like a dictionary holding nested dictionaries with lists of lists and tuples and sets.
The sys.getsizeof function does a shallow size of only. It counts each object inside a container as pointer only regardless of how big it really is.
- Parameters:
o (obj) – the object
ids (set) – used to hold object id(s)
- Returns:
The memory footprint of the object in bytes
7.3.1.1.7. omega_model.common.omega_globals module
OMEGA global variables.
Runtime options to be populated during initialization.
CODE
- options = None
simulation options
- pass_num = 0
multi-pass pass number
- manufacturer_aggregation = False
true if manufacturer-level detail in vehicle aggregation
- price_modification_data = None
holds price modification data for the current compliance_id and calendar year
- locked_price_modification_data = None
holds price locked modification data for the current compliance_id and calendar year
- cumulative_battery_GWh = {'total': 0}
holds cumulative battery GWh production, by calendar year, from first pass
round to the Nth digit when calculating share values in constraint dicts
- constraints = {}
dict of constraint dicts by market category
- finalized_vehicles = []
finalized vehicles
7.3.1.1.8. omega_model.common.omega_log module
Functions to manage batch and session log files.
CODE
- class IterationLog(logfilename)
Bases:
OMEGABase
Handles creation and writing of a dataframe to a .csv file, possibly multiple times via appending. Used to log producer-consumer iteration, but could be used to log any dataframe.
- __init__(logfilename)
Create IterationLog object
- Parameters:
logfilename – name of file to create, ‘.csv’ extension added if not provided.
- write(dataframe)
Write dataframe to a .csv file, file is created on first write, subsequent writes append.
- Parameters:
dataframe (DataFrame) – dataframe to write to file
- class OMEGABatchLog(o2_options, verbose=True)
Bases:
OMEGABase
Handles logfile creation at the batch level.
- __init__(o2_options, verbose=True)
Create OMEGABatchLog object
- Parameters:
o2_options (OMEGABatchOptions) – provides the logfile name
verbose (bool) – if True enables optional output to console as well as logfile
- logwrite(message, terminator='\n')
Write a message to a logfile (and console if verbose)
- Parameters:
message (str) – message string to write
terminator (str) – end of message terminator, default is newline (
\n
)
- end_logfile(message)
End logfile with closing message, record elapsed time.
- Parameters:
message (str) – message string to write
- init_logfile(compliance_id=None)
Create a session logfile.
- Parameters:
compliance_id (str) – added to log file name if provided
- end_logfile(message)
End logfile with closing message, record elapsed time.
- Parameters:
message (str) – message string to write
- logwrite(message, echo_console=True, terminator='\n')
Write message to logfile.
- Parameters:
message (str or [strs]) – message string or list of strings to write
echo_console (bool) – write message to console if True
terminator (str) – end of message terminator, default is newline (
\n
)
7.3.1.1.9. omega_model.common.omega_plot module
Handy plotting functions for matplotlib plots.
CODE
- label_xy(ax, x_label_str, y_label_str)
Label x-axis and y-axis.
- Parameters:
ax (matplotlib.axes._subplots.AxesSubplot) – the axis (plot) to label
x_label_str (str) – x-axis label
y_label_str (str) – y-axis label
- label_xyt(ax, x_label_str, y_label_str, title_str)
Label x-axis, y-axis and set axis title.
- Parameters:
ax (matplotlib.axes._subplots.AxesSubplot) – the axis(plot) to label
x_label_str (str) – x-axis label
y_label_str (str) – y-axis label
title_str (str) – axis title
Returns:
- lineat(ax, y, *args, **kwargs)
Draw a horizontal line at a y-value.
- Parameters:
ax (matplotlib.axes._subplots.AxesSubplot) – the axis (plot) to draw on
y (numeric) – the vertical index of the line
*args – optional positional arguments to pyplot.plot()
**kwargs – optional keyword arguments to pyplot.plot()
- vlineat(ax, x, *args, **kwargs)
Draw a vertical line at an x-value.
- Parameters:
ax (matplotlib.axes._subplots.AxesSubplot) – the axis to draw on
x (numeric) – the horizontal index of the line
*args – optional positional arguments to pyplot.plot()
**kwargs – optional keyword arguments to pyplot.plot()
- figure(reuse_figure=False)
Create a figure window with a single plot axis.
- Returns:
2-tuple of figure and axis objects, respectively.
- fplothg(x, y, *args, reuse_figure=False, **kwargs)
Shortcut for figure, plot, hold on, grid on (based on Matlab plotting terminology) Creates a single axis plot, with grid.
- Parameters:
x – x-values of data to plot
y – y-values of data to plot
*args – optional positional arguments to pyplot.plot()
reuse_figure (bool) – re-use figure window if
True
**kwargs – optional keyword arguments to pyplot.plot()
- Returns:
2-tuple of figure and axis objects, respectively.
- fplotyyhg(x, y, ylinespec, y2, y2linespec)
Shortcut for figure, plotyy, hold on, grid on (based on Matlab plotting terminology). Creates a plot with a double y-axis and grid.
- Parameters:
x – x-values of data to plot
y – y-values of data to plot on first y-axis
ylinespec (str) – line format string, e.g. ‘b.-’
y2 – y-values of data to plot on second y-axis
y2linespec (str) – line format string, e.g. ‘r.-’
- Returns:
3-tuple of figure and two axis objects, respectively.
7.3.1.1.10. omega_model.common.omega_trees module
Routines and data structures for tree-based algorithms and functions.
CODE
- class WeightedNode(weight)
Bases:
OMEGABase
Implements nodes in a tree where nodes have weights and values. Used for drive cycle weighting, but could also be used for weighting in general, if needed.
WeightedNodes
are stored as node data in aWeightedTree.tree
(see below), which is atreelib.Tree
.- __init__(weight)
Create WeightedNode
- Parameters:
weight (numeric) – node weight
- property weighted_value
Calculate node weighted value.
- Returns:
Node weight times node value if weight is not
None
, else returns 0.
- property identifier
Generate a node ID string.
- Returns:
Node ID string.
- class WeightedTree(tree_df, verbose=False)
Bases:
OMEGABase
Implements a tree data structure of
WeightedNodes
and methods of querying node values.- __init__(tree_df, verbose=False)
Create WeightedTree from a dataframe containing node connections as column headers and weights as row values.
- Parameters:
tree_df (DataFrame) – a dataframe with column headers such as
'A->B', 'A->C', 'B->D'
etc.verbose (bool) – prints the tree to the console if True
Note
The first element of the first column containing an arrow (
->
) is taken as the root node. Parent nodes must be referenced before child nodes, otherwise there is no particular pre-defined order. In the above example, B is a child of A before D can be a child of B.
- leaves()
Get list of tree leaves.
- Returns:
List of tree nodes (type
treelib.node.Node
) that have no children.
- validate_weights()
Validated node weights. The sum of a parent node’s child node weights must equal 1.0. Nodes with a weight of
None
are ignored during summation.- Returns:
List of node weight errors, or empty list on success.
- static calc_node_weighted_value(tree, node_id, weighted=True)
Calculate node weighted value. If the node has no children then the weighted value is the node’s weighted value, see
WeightedNode
above. If the node has children then the weighted value is the sum of the weighted values of the children, recursively if necessary.- Parameters:
tree (treelib.Tree) – the tree to query
node_id (str) – the id of the node to query
weighted (bool) – if
True
then return weighted value string, else return node value string
- Returns:
(node weighted value, equation string)
- Return type:
tuple
- calc_value(values_dict, node_id=None, weighted=False)
Assign values to tree leaves then calculate the value or weighted value at the given
node_id
or at the root if nonode_id
is provided. Previously calculated values are cleared first.- Parameters:
values_dict (dict-like) – values to assign to leaves
node_id (str) – node id to calculate weighted value of, or tree root if not provided
weighted (bool) – if True then return weighted value, else return node value
- Returns:
Node (or tree) value (or weighted value)
- show()
Print the tree to the console.
7.3.1.1.11. omega_model.common.omega_types module
Custom general datatypes for use in OMEGA.
CODE
- make_valid_python_identifier(s)
Creates a valid python identifier from a source string (by removing invalid characters).
- Parameters:
s (str) – the source string to make a valid identifier from
- Returns:
A valid python identifier based on the source string
- class OMEGABase
Bases:
object
Defines a base class with common behaviors for all OMEGA objects.
Example of representation strings and printing via
__repr__
and__str__
methods:class ExampleOMEGAClass(OMEGABase): def __init__(self): self.first_attribute = 0 self.second_attribute = 1 >>>example_object = ExampleOMEGAClass() >>>example_object <OMEGA2 ExampleOMEGAClass object at 0x7f91d03975e0> >>>print(example_object) <OMEGA2 ExampleOMEGAClass object at 0x7f91d03975e0> first_attribute = 0 second_attribute = 1
- classmethod get_class_attributes(attribute_list)
Get a list of class attributes.
- Parameters:
cls (class) – the class to get attributes from
attribute_list ([strs]) – a list of attribute names
- Returns:
A list containing the values of the requested attributes
- __repr__()
Generate a representation string for the object.
- Returns:
A string representation of the object.
- __str__()
Generate a string of object attributes, so objects have a default print behavior.
- Returns:
A string with a listing of object attributes and values.
- get_object_attributes(attribute_list)
Get a list of object attributes.
- Parameters:
self (object) – the object to get attributes from
attribute_list ([strs]) – a list of attribute names
- Returns:
A list containing the values of the requested attributes
- to_dataframe(types=None)
Generate a dataframe of object attributes as numeric values or strings
- Returns:
A dataframe representation of the object
- to_csv(filename, transpose=True, *args, **kwargs)
Save object as comma-separated values file.
- Parameters:
filename (str) – name of file
transpose (bool) – tranpose dataframe if
True
*args – optional positional arguments to pandas DataFrame.to_csv()
**kwargs – optional keyword arguments to pandas DataFrame.to_csv()
- to_dict(types=None)
Generate a dict of object attributes
- Returns:
A dict representation of the object
- to_namedtuple()
Generate a named tuple of object attributes
- Returns:
A namedtuple representation of the ojbect
- copy()
Copy object
- Returns:
Copy of the current object
- deepcopy()
Deep copy object
- Returns:
Deep copy of the current object
- class OMEGAEnum(enum_list)
Bases:
OMEGABase
Simple enumerated value class, which acts like a list of strings, has named attributes which contain the attribute name as a string, also acts like a dictionary.
Example
# define an OMEGAEnum reg_classes = OMEGAEnum(['car', 'truck']) # named attribute behavior >>>reg_classes.car 'car' # dict-like behavior >>>reg_classes['car'] 'car' >>>reg_classes.keys() dict_keys(['car', 'truck']) >>>reg_classes.values() dict_values(['car', 'truck']) >>>reg_classes.items() dict_items([('car', 'car'), ('truck', 'truck')]) # list-like behavior >>>[rc for rc in reg_classes] ['car', 'truck']
- __init__(enum_list)
Create OMEGAEnum object from list of values.
- Parameters:
enum_list (list) – list of enumeration values
- values()
Implement values() function, like a dict.
- Returns:
A list of values
- keys()
Implement keys() function, like a dict.
- Returns:
A list of keys
- items()
Implement items() function, like a dict.
- Returns:
A list of key-value pairs (2-tuples)
7.3.1.2. omega_model.consumer package
The consumer package defines market classes, their associated properties, and routines to determine consumer desired market shares as a function of market class, relative costs, etc. The consumer module also handles vehicle re-registration.
CODE
7.3.1.2.1. Submodules
7.3.1.2.2. omega_model.consumer.annual_vmt_fixed_by_age module
Routines to load and provide access to annual vehicle miles travelled (VMT) by market class and age.
The data represents a fixed VMT schedule by age.
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows. The template header uses a dynamic format.
The data represents the re-registered proportion of vehicles by calendar year, age and market class.
- File Type
comma-separated values (CSV)
- Template Header
input_template_name:
[module_name]
input_template_version:
[template_version]
- Sample Header
input_template_name:
consumer.annual_vmt_fixed_by_age
input_template_version:
0.2
notes:
20221116 vmt schedule by body style
- Sample Data Columns
start_year
age
market_class_id
annual_vmt
2019
0
sedan_wagon.BEV
15922
2019
1
sedan_wagon.BEV
15379
2019
2
sedan_wagon.BEV
14864
2019
0
pickup.ICE
18964
2019
1
pickup.ICE
17986
2019
2
pickup.ICE
17076
2019
0
cuv_suv_van.PHEV
16234
2019
1
cuv_suv_van.PHEV
15805
2019
2
cuv_suv_van.PHEV
15383
- start_year:
Start year of annual VMT data, values apply until the next available start year
- age:
Vehicle age, in years
- market_class_id:
Vehicle market class ID, e.g. ‘sedan_wagon.ICE’
- annual_vmt:
Vehicle miles travelled per year at the given age for the given market class ID
CODE
- class OnroadVMT
Bases:
OMEGABase
,AnnualVMTBase
Loads and provides access to annual Vehicle Miles Travelled by calendar year, market class, and age.
- cumulative_vmt = {}
- static get_vmt(calendar_year, market_class_id, age)
Get vehicle miles travelled by calendar year, market class and age.
- Parameters:
calendar_year (int) – calendar year of the VMT data
market_class_id (str) – market class id, e.g. ‘sedan_wagon.ICE’
age (int) – vehicle age in years
- Returns:
(float) Annual vehicle miles travelled.
- static get_cumulative_vmt(market_class_id, age)
Get the cumulative VMT for the given market class and age
- Parameters:
market_class_id (str) – market class id, e.g. ‘sedan_wagon.ICE’
age (int) – vehicle age in years
- Returns:
The cumulative VMT for the given market class and age
- static init_from_file(filename, verbose=False)
Initialize class data from input file.
- Parameters:
filename (str) – name of input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
7.3.1.2.3. omega_model.consumer.consumer_base_classes module
A set of base classes used to define the program interface(s) and to serve as templates for user-defined classes
Ordinarily these classes might be implemented as Python abstract classes but abstract classes cause issues when combined with SQLAlchemy base classes, so the implementation here is a workaround - if a child class fails to implement one of the required methods, the class will throw a runtime Exception or return an error message.
- class ReregistrationBase
Bases:
object
Load and provide access to vehicle re-registration data by model year, market class ID and age.
- static get_reregistered_proportion(model_year, market_class_id, age)
Get vehicle re-registered proportion [0..1] by market class and age.
- Parameters:
model_year (int) – the model year of the re-registration data
market_class_id (str) – market class id, e.g. ‘sedan_wagon.ICE’
age (int) – vehicle age in years
- Returns:
Re-registered proportion [0..1]
- static init_from_file(filename, verbose=False)
Initialize class data from input file.
- Parameters:
filename (str) – name of input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
- class AnnualVMTBase
Bases:
object
Loads and provides access to annual Vehicle Miles Travelled by calendar year, market class, and age.
- static get_vmt(calendar_year, market_class_id, age)
Get vehicle miles travelled by calendar year, market class and age.
- Parameters:
calendar_year (int) – calendar year of the VMT data
market_class_id (str) – market class id, e.g. ‘sedan_wagon.ICE’
age (int) – vehicle age in years
- Returns:
(float) Annual vehicle miles travelled.
- static init_from_file(filename, verbose=False)
Initialize class data from input file.
- Parameters:
filename (str) – name of input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
Bases:
object
Class to calculate absolute market shares by market class
Determine consumer desired market shares for the given vehicles, their costs, etc. Relative shares are first calculated within non-responsive market categories then converted to absolute shares.
- Parameters:
calendar_year (int) – calendar year to calculate market shares in
compliance_id (str) – manufacturer name, or ‘consolidated_OEM’
producer_decision (Series) – selected producer compliance option
market_class_data (DataFrame) – DataFrame with ‘average_fuel_price_MC’, ‘average_modified_cross_subsidized_price_MC’, ‘average_co2e_gpmi_MC’, ‘average_kwh_pmi_MC’ columns, where MC = market class ID
mc_parent (str) – e.g. ‘’ for the total market, ‘pickup’ or ‘sedan_wagon’, etc
mc_pair ([strs]) – e.g. ‘[‘pickup’, ‘sedan_wagon’] or [‘pickup.ICE’, ‘pickup.BEV’], etc
- Returns:
A copy of
market_class_data
with demanded ICE/BEV share columns by market class, e.g. ‘consumer_share_frac_MC’, ‘consumer_abs_share_frac_MC’, and ‘consumer_generalized_cost_dollars_MC’ where MC = market class ID
Save calibration data (if necessary) that aligns reference session market shares with context
- Parameters:
filename (str) – name of the calibration file
Store producer decision and response (if necessary) for reference in future years
- Parameters:
producer_decision_and_response (Series) – producer decision and consumer response
Calculate base year data (if necessary) such as sales-weighted curbweight, etc, if needed for reference in future years
- Parameters:
base_year_vehicles_df (DataFrame) – base year vehicle data
Initialize class data from input file.
- Parameters:
filename (str) – name of input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
- class MarketClassBase
Bases:
object
Loads market class definition data and provides market-class-related functionality.
- market_classes = ()
tuple of market classes
- market_categories = []
- responsive_market_categories = []
- non_responsive_market_categories = []
- electrified_market_categories = []
- linked_market_classes = {}
- static get_linestyle(varname)
- Parameters:
varname (str) – variable name, e.g. ‘sedan_wagon.ICE’, ‘BEV’, etc
- Returns:
dict of linestyle arguments
For colors see: https://matplotlib.org/stable/gallery/color/named_colors.html For linestyles see: https://matplotlib.org/stable/gallery/lines_bars_and_markers/linestyles.html
- static parse_market_classes(market_class_list, market_class_dict=None, by_reg_class=False)
Returns a nested dictionary of market classes from a dot-formatted list of market class names.
- Parameters:
market_class_list ([strs]) – list of dot-separted market class names e.g. [‘pickup.BEV’, ‘pickup.ICE’] etc
market_class_dict (dict, dict of dicts) – recursive input and also the output data structure
by_reg_class (bool) – if true then leaves are lists in reg class dicts, otherwise leaves are lists by market segment
- Returns:
Market class tree represented as a dict or dict of dicts, with an empty list at each leaf. e.g.
{'sedan_wagon': {'BEV': [], 'ICE': []}, 'pickup': {'BEV': [], 'ICE': []}}
- static populate_market_classes(market_class_dict, market_class_id, obj)
Populate the leaves of a market class tree implemented as a dict (or dict of dicts) where the keys represent market categories and the leaves are lists of objects grouped by market class.
- Parameters:
market_class_dict (dict) – dict of dicts of market classes
market_class_id (str) – dot separated market class name e.g. ‘pickup.BEV’, possibly with reg class suffix e.g. ‘sedan_wagon.ICE.car’ depending on the market_class_dict
obj (obj) – object to place in a list in the appropriate leaf, as in a CompositeVehicle
- Returns:
Nothing, modifies
market_class_dict
data
- static get_market_class_dict()
Get a copy of the market class dict with an empty list for each market class.
- Returns:
A copy of the market class dict.
- static get_market_class_tree(by_reg_class=False)
Get a copy of a hierarchical market class dict with empty lists for each market class or by regulatory class within the market class.
- Parameters:
by_reg_class (bool) – if True then return a tree by reg class within market class.
- Returns:
A copy of the appropriate hierarchical market class dict.
- static get_vehicle_market_class(vehicle)
Get vehicle market class ID based on vehicle characteristics
- Parameters:
vehicle (Vehicle) – the vehicle to determine the market class of
- Returns:
The vehicle’s market class ID based on vehicle characteristics.
- static get_non_responsive_market_category(market_class_id)
Returns the non-responsive market category of the given market class ID
- Parameters:
market_class_id (str) – market class ID, e.g. ‘sedan_wagon.ICE’
- Returns:
The non-responsive market category of the given market class ID
- static validate_market_class_id(market_class_id)
Validate market class ID
- Parameters:
market_class_id (str) – market class ID, e.g. ‘sedan_wagon.ICE’
- Returns:
Error message in a list if market_class_id is not valid
- static init_from_file(filename, verbose=False)
Initialize class data from input file.
- Parameters:
filename (str) – name of input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
7.3.1.2.4. omega_model.consumer.market_classes_ice_bev_phev_body_style module
Routines to implement market-class related functionality.
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows. The template header uses a dynamic format.
The data represents characteristics of the Consumer Module’s market classes.
- File Type
comma-separated values (CSV)
- Template Header
input_template_name:
[module_name]
input_template_version:
[template_version]
[other]
- Sample Header
input_template_name:
consumer.market_classes_body_style
input_template_version:
0.1
- Sample Data Columns
market_class_id
fueling_class
ownership_class
sedan_wagon.BEV
BEV
private
cuv_suv_van.ICE
ICE
private
Data Column Name and Description
- market_class_id:
Vehicle market class ID, e.g. ‘sedan_wagon.ICE’
- fueling_class:
Market class fueling class, e.g. ‘BEV’, ‘ICE’
- ownership_class:
Market class ownership class, e.g. ‘private’, ‘shared’ (For future development)
CODE
- class MarketClass
Bases:
OMEGABase
,MarketClassBase
Loads market class definition data and provides market-class-related functionality.
- market_categories = ['ICE', 'BEV', 'PHEV', 'sedan_wagon', 'cuv_suv_van', 'pickup']
overall market categories
- responsive_market_categories = ['ICE', 'BEV', 'PHEV']
market categories that have consumer response (i.e. price -> sales)
- non_responsive_market_categories = ['sedan_wagon', 'cuv_suv_van', 'pickup']
market categories that do not have consumer response
- electrified_market_categories = ['BEV', 'PHEV']
- static get_linestyle(varname)
- Parameters:
varname (str) – market class string, e.g. ‘sedan_wagon.ICE’
- Returns:
dict of linestyle arguments
For colors see: https://matplotlib.org/stable/gallery/color/named_colors.html For linestyles see: https://matplotlib.org/stable/gallery/lines_bars_and_markers/linestyles.html
- static get_vehicle_market_class(vehicle)
Get vehicle market class ID based on vehicle characteristics
- Parameters:
vehicle (Vehicle) – the vehicle to determine the market class of
- Returns:
The vehicle’s market class ID based on vehicle characteristics.
- static get_non_responsive_market_category(market_class_id)
Returns the non-responsive market category of the given market class ID
- Parameters:
market_class_id (str) – market class ID, e.g. ‘sedan_wagon.ICE’
- Returns:
The non-responsive market category of the given market class ID
- static validate_market_class_id(market_class_id)
Validate market class ID
- Parameters:
market_class_id (str) – market class ID, e.g. ‘sedan_wagon.ICE’
- Returns:
Error message in a list if market_class_id is not valid
- static init_from_file(filename, verbose=False)
Initialize class data from input file.
- Parameters:
filename (str) – name of input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
7.3.1.2.5. omega_model.consumer.market_classes_ice_bev_phev_body_style_zevregion module
Routines to implement market-class related functionality.
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows. The template header uses a dynamic format.
The data represents characteristics of the Consumer Module’s market classes.
- File Type
comma-separated values (CSV)
- Template Header
input_template_name:
[module_name]
input_template_version:
[template_version]
[other]
- Sample Header
input_template_name:
consumer.market_classes_body_style
input_template_version:
0.1
- Sample Data Columns
market_class_id
fueling_class
ownership_class
sedan_wagon.BEV
BEV
private
cuv_suv_van.ICE
ICE
private
Data Column Name and Description
- market_class_id:
Vehicle market class ID, e.g. ‘sedan_wagon.ICE’
- fueling_class:
Market class fueling class, e.g. ‘BEV’, ‘ICE’
- ownership_class:
Market class ownership class, e.g. ‘private’, ‘shared’ (For future development)
CODE
- class MarketClass
Bases:
OMEGABase
,MarketClassBase
Loads market class definition data and provides market-class-related functionality.
- market_categories = ['ICE', 'BEV', 'PHEV', 'sedan_wagon_r1nonzev', 'cuv_suv_van_r1nonzev', 'pickup_r1nonzev', 'sedan_wagon_r2zev', 'cuv_suv_van_r2zev', 'pickup_r2zev']
overall market categories
- responsive_market_categories = ['ICE', 'BEV', 'PHEV']
market categories that have consumer response (i.e. price -> sales)
- non_responsive_market_categories = ['sedan_wagon_r1nonzev', 'cuv_suv_van_r1nonzev', 'pickup_r1nonzev', 'sedan_wagon_r2zev', 'cuv_suv_van_r2zev', 'pickup_r2zev']
market categories that do not have consumer response
- electrified_market_categories = ['BEV', 'PHEV']
- linked_market_classes = {'cuv_suv_van_r2zev.ICE': 'cuv_suv_van_r1nonzev.ICE', 'cuv_suv_van_r2zev.PHEV': 'cuv_suv_van_r1nonzev.PHEV', 'pickup_r2zev.ICE': 'pickup_r1nonzev.ICE', 'pickup_r2zev.PHEV': 'pickup_r1nonzev.PHEV', 'sedan_wagon_r2zev.ICE': 'sedan_wagon_r1nonzev.ICE', 'sedan_wagon_r2zev.PHEV': 'sedan_wagon_r1nonzev.PHEV'}
- static get_linestyle(varname)
- Parameters:
varname (str) – market class string, e.g. ‘sedan_wagon.ICE’
- Returns:
dict of linestyle arguments
For colors see: https://matplotlib.org/stable/gallery/color/named_colors.html For linestyles see: https://matplotlib.org/stable/gallery/lines_bars_and_markers/linestyles.html
- static get_vehicle_market_class(vehicle)
Get vehicle market class ID based on vehicle characteristics
- Parameters:
vehicle (Vehicle) – the vehicle to determine the market class of
- Returns:
The vehicle’s market class ID based on vehicle characteristics.
- static get_non_responsive_market_category(market_class_id)
Returns the non-responsive market category of the given market class ID
- Parameters:
market_class_id (str) – market class ID, e.g. ‘sedan_wagon.ICE’
- Returns:
The non-responsive market category of the given market class ID
- static validate_market_class_id(market_class_id)
Validate market class ID
- Parameters:
market_class_id (str) – market class ID, e.g. ‘sedan_wagon.ICE’
- Returns:
Error message in a list if market_class_id is not valid
- static init_from_file(filename, verbose=False)
Initialize class data from input file.
- Parameters:
filename (str) – name of input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
7.3.1.2.6. omega_model.consumer.reregistration_fixed_by_age module
Vehicle re-registration, fixed by age.
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows. The template header uses a dynamic format.
The data represents the re-registered proportion of vehicles by model year, age and market class.
- File Type
comma-separated values (CSV)
- Template Header
input_template_name:
[module_name]
input_template_version:
[template_version]
- Sample Header
input_template_name:
consumer.reregistration_fixed_by_age
input_template_version:
0.2
- Sample Data Columns
start_model_year
age
market_class_id
reregistered_proportion
1970
0
sedan_wagon.BEV
1
1970
1
sedan_wagon.BEV
0.987841531
1970
2
sedan_wagon.BEV
0.976587217
1970
0
cuv_suv_van.ICE
1
1970
1
cuv_suv_van.ICE
0.987841531
1970
2
cuv_suv_van.ICE
0.976587217
Data Column Name and Description
- start_model_year:
The start vehicle model year of the re-registration data, values apply until next available start year
- age:
Vehicle age, in years
- market_class_id:
Vehicle market class ID, e.g. ‘sedan_wagon.ICE’
- reregistered_proportion:
The fraction of vehicles re-registered, [0..1]
CODE
- class Reregistration
Bases:
OMEGABase
,ReregistrationBase
Load and provide access to vehicle re-registration data by model year, market class ID and age.
- static get_reregistered_proportion(model_year, market_class_id, age)
Get vehicle re-registered proportion [0..1] by market class and age.
- Parameters:
model_year (int) – the model year of the re-registration data
market_class_id (str) – market class id, e.g. ‘sedan_wagon.ICE’
age (int) – vehicle age in years
- Returns:
Re-registered proportion [0..1]
- static init_from_file(filename, verbose=False)
Initialize class data from input file.
- Parameters:
filename (str) – name of input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
7.3.1.2.9. omega_model.consumer.sales_volume module
Routines to retrieve overall sales from the context and total consumer sales response as a function of total sales-weighted generalized cost.
CODE
- context_new_vehicle_sales(calendar_year)
Get new vehicle sales from the context.
- Parameters:
calendar_year (int) – the year to get sales for
- Returns:
dict of vehicle sales by non-responsive market category, and
total
- log_new_vehicle_generalized_cost(calendar_year, compliance_id, P)
- Parameters:
calendar_year (int) – the calendar year to calculate sales in
compliance_id (str) – manufacturer name, or ‘consolidated_OEM’
P ($, [$]) – a single price representing the final production decision average new vehicle generalized cost
- new_vehicle_sales_response(calendar_year, compliance_id, P)
Calculate new vehicle sales fraction relative to a reference sales volume and average new vehicle generalized cost. Updates generalized cost table associated with the reference session so those costs can become the reference costs for subsequent sessions.
- Parameters:
calendar_year (int) – the calendar year to calculate sales in
compliance_id (str) – manufacturer name, or ‘consolidated_OEM’
P ($, [$]) – a single price or a list/vector of prices
- Returns:
Relative new vehicle sales volume at each price, e.g.
0.97
,1.03
, etc
- init_sales_volume()
Initialize the module by clearing the cache.
7.3.1.2.10. omega_model.consumer.stock module
Routines to implement vehicle re-registration on an annual basis as a function of vehicle attributes.
CODE
- get_vehicle_info(vehicle_id)
Gets vehicle info for the given vehicle ID
- Parameters:
vehicle_id (str) – the vehicle ID (e.g. ‘OEM_42’)
- Returns:
Vehicle market_class_id, model_year, initial_registered_count
- update_stock(calendar_year, compliance_id=None)
Re-register vehicles by calendar year, as a function of vehicle attributes (e.g. age, market class…) Also calculates vehicle miles travelled for each vehilce by market class and age.
- Parameters:
compliance_id (str) – optional argument, manufacturer name, or ‘consolidated_OEM’
calendar_year (int) – calendar year to re-register vehicles in
- Returns:
Nothing, updates VehicleAnnualData entries (
age
,registered_count
,annual_vmt
,vmt
).
7.3.1.3. omega_model.context package
OMEGA analysis context subpackage
CODE
7.3.1.3.1. Submodules
7.3.1.3.2. omega_model.context.body_styles module
Routines to load, validate, and provide access to body style definition data
Body styles defined by a name and a brief description.
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows.
The data represents body style names and a brief description.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
body_styles
input_template_version:
0.1
- Sample Data Columns
body_style_id
description
sedan
Non-pickup / non-crossover / non-sport-utility vehicle
pickup
Pickup truck / body-on-frame vehicle
cuv_suv
Crossover / sport-utility vehicle
Data Column Name and Description
- body_style_id:
Name of the body style
- description:
A brief description of the body style
CODE
- class BodyStyles
Bases:
OMEGABase
Load and provides routines to access drive cycle descriptive data
- body_styles = []
list of available body styles
- static init_from_file(filename, verbose=False)
Initialize class data from input file.
- Parameters:
filename (str) – name of input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
7.3.1.3.3. omega_model.context.context_base_classes module
Context base classes.
Currently just CostCloudBase
.
- class CostCloudBase
Bases:
object
Loads and provides access to simulated vehicle data, provides methods to calculate and plot frontiers.
- static init_cost_clouds_from_files(ice_filename, bev_filename, phev_filename, verbose=False)
Initialize class data from input file.
- Parameters:
ice_filename (str) – name of ICE/HEV vehicle simulation data input file
bev_filename (str) – name of BEV vehicle simulation data input file
phev_filename (str) – name of PHEV vehicle simulation data input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
- static get_cloud(vehicle)
Retrieve cost cloud for the given vehicle.
- Parameters:
() (vehicle) – the vehicle to get the cloud for
- Returns:
Copy of the requested cost cload data.
7.3.1.3.4. omega_model.context.electricity_prices_aeo module
Routines to load and access electricity prices from the analysis context
AEO electricity price data include retail and pre-tax costs in dollars per unit (e.g. $/kWh)
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows. The template header uses a dynamic format.
The data represents electricity prices by context case and calendar year.
- File Type
comma-separated values (CSV)
- Template Header
input_template_name:
[module_name]
input_template_version:
[template_version]
[other]
- Sample Header
input_template_name:
context.electricity_prices_aeo
input_template_version:
0.2
description:
20230602-130256_run
- Sample Data Columns
context_id
dollar_basis
case_id
fuel_id
calendar_year
retail_dollars_per_unit
pretax_dollars_per_unit
AEO2020
2019
Reference case
US electricity
2019
0.12559407
0.10391058
AEO2020
2019
Reference case
US electricity
2020
0.1239522
0.10212733
- Data Column Name and Description
- context_id:
The name of the context source, e.g. ‘AEO2020’, ‘AEO2021’, etc
- dollar_basis:
The dollar basis of the fuel prices in the given AEO version. Note that this dollar basis is converted in-code to ‘analysis_dollar_basis’ using the implicit_price_deflators input file.
- case_id:
The name of the case within the context, e.g. ‘Reference Case’, ‘High oil price’, etc
- fuel_id:
The name of the vehicle in-use fuel, must be in the table loaded by
class fuels.Fuel
and consistent with the base year vehicles file (columnin_use_fuel_id
) loaded byclass vehicles.VehicleFinal
- calendar_year:
The calendar year of the fuel costs
- retail_dollars_per_unit:
Retail dollars per unit
- pretax_dollars_per_unit:
Pre-tax dollars per unit
CODE
- class ElectricityPrices
Bases:
OMEGABase
Loads and provides access to fuel prices from the analysis context
- year_min = None
- year_max = None
- static get_fuel_price(calendar_year)
Get fuel price data for fuel_id in calendar_year
- Parameters:
calendar_year (numeric) – calendar year for which a price is sought
- Returns:
Fuel price for the passed calendar year
- static init_from_file(filename, verbose=False)
Initialize class data from input file.
- Parameters:
filename (str) – name of input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
7.3.1.3.6. omega_model.context.fuel_prices module
Routines to load and access fuel prices from the analysis context
Context fuel price data includes retail and pre-tax costs in dollars per unit (e.g. $/gallon, $/kWh)
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows.
The data represents fuel prices by context case, fuel type, and calendar year.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
context_fuel_prices
input_template_version:
0.2
- Sample Data Columns
context_id
dollar_basis
case_id
fuel_id
calendar_year
retail_dollars_per_unit
pretax_dollars_per_unit
AEO2020
2019
Reference case
pump gasoline
2019
2.665601
2.10838
AEO2020
2019
Reference case
US electricity
2019
0.12559407
0.10391058
- Data Column Name and Description
- context_id:
The name of the context source, e.g. ‘AEO2020’, ‘AEO2021’, etc
- dollar_basis:
The dollar basis of the fuel prices in the given AEO version. Note that this dollar basis is converted in-code to ‘analysis_dollar_basis’ using the implicit_price_deflators input file.
- case_id:
The name of the case within the context, e.g. ‘Reference Case’, ‘High oil price’, etc
- fuel_id:
The name of the vehicle in-use fuel, must be in the table loaded by
class fuels.Fuel
and consistent with the base year vehicles file (columnin_use_fuel_id
) loaded byclass vehicles.Vehicle
- calendar_year:
The calendar year of the fuel costs
- retail_dollars_per_unit:
Retail dollars per unit
- pretax_dollars_per_unit:
Pre-tax dollars per unit
CODE
- class FuelPrice
Bases:
OMEGABase
Loads and provides access to fuel prices from the analysis context
- static get_fuel_prices(calendar_year, price_types, fuel_id)
Get fuel price data for fuel_id in calendar_year
- Parameters:
calendar_year (numeric) – calendar year to get price in
price_types (str, [str1, str2...]) – ContextFuelPrices attributes to get
fuel_id (str) – fuel ID
- Returns:
Fuel price or tuple of fuel prices if multiple attributes were requested
Example
pretax_pump_gas_price_dollars_2030 = ContextFuelPrices.get_fuel_prices(2030, 'pretax_dollars_per_unit', 'pump gasoline') pump_gas_attributes_2030 = ContextFuelPrices.get_fuel_prices(2030, ['retail_dollars_per_unit', 'pretax_dollars_per_unit'], 'pump gasoline')
- static init_from_file(filename, verbose=False)
Initialize class data from input file.
- Parameters:
filename (str) – name of input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
7.3.1.3.7. omega_model.context.glider_cost module
Routines to calculate glider cost.
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows. The template header uses a dynamic format.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
glider_cost
input_template_version:
0.11
notes:
20220719 structure costs for aluminum BIW aligned with FEV Venza and Silverado teardowns
- Sample Data Columns
body_style
item
material
value
dollar_basis
sedan
unibody_structure
steel
(1.5 * structure_mass_lbs + 1500) * markup
2020
sedan
unibody_structure
aluminum
(3.4 * structure_mass_lbs + 1500) * markup
2020
cuv_suv
unibody_structure
aluminum
(3.4 * structure_mass_lbs + 1700) * markup
2020
- Data Column Name and Description
- body_style:
Vehicle body style, e.g. ‘sedan’, ‘ALL’, etc
- item:
Name of the glider cost parameter, e.g. ‘unibody_structure’, ‘learning_rate’, etc
- material:
Parameter material type, e.g. ‘steel’, ‘aluminum’, etc
- value:
The parameter cost value or equation to be evaulated
- dollar_basis:
The dollar basis year for the cost value, e.g.
2020
CODE
- class GliderCost
Bases:
OMEGABase
Loads and provides access to glider cost data, provides methods to calculate glider costs.
- static get_markups_and_learning(vehicle)
- Parameters:
vehicle –
Returns:
- static get_base_year_glider_non_structure_cost(vehicle, structure_mass_lbs, powertrain_cost)
Calculate the base year glider non-structure cost.
- Parameters:
vehicle (Vehicle) – the vehicle to calculate the glider non-structure cost for
structure_mass_lbs (float) – vehicle structure mass in pounds
powertrain_cost (float) – powertrain cost in dollars
- Returns:
Vehicle base year glider non-structure cost.
- static calc_cost(vehicle, pkg_df)
Calculate the value of the response surface equation for the given powertrain type, cost curve class (tech package) for the full factorial combination of the iterable terms.
- Parameters:
vehicle (Vehicle) – the vehicle to calc costs for
pkg_df (DataFrame) – the necessary information for developing cost estimates.
- Returns:
A list of cost values indexed the same as pkg_df.
- static init_from_file(filename, verbose=False)
Initialize class data from input file.
- Parameters:
filename (str) – name of input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
7.3.1.3.8. omega_model.context.ip_deflators module
Routines to load Implicit Price (IP) deflators.
Used to convert monetary inputs to a consistent dollar basis, e.g., in the cost_factors_congestion_noise
module.
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows.
The data represents the price deflator by calendar year.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
context_implicit_price_deflators
input_template_version:
0.22
- Sample Data Columns
calendar_year
price_deflator
2001
79.783
2002
81.026
Data Column Name and Description
- calendar_year:
Calendar year of the price deflator
- price_deflator:
Implicit price deflator
CODE
- class ImplicitPriceDeflators
Bases:
OMEGABase
Loads and provides access to implicit price deflators by calendar year.
- static get_price_deflator(calendar_year)
Get the implicit price deflator for the given calendar year.
- Parameters:
calendar_year (int) – the calendar year to get the function for
- Returns:
The implicit price deflator for the given calendar year.
- static dollar_adjustment_factor(dollar_basis_input)
- Parameters:
dollar_basis_input (int) – the dollar basis of the input value.
- Returns:
The multiplicative factor that can be applied to a cost in dollar_basis_input to express that value in analysis_dollar_basis.
- static init_from_file(filename, verbose=False)
Initialize class data from input file.
- Parameters:
filename (str) – name of input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
7.3.1.3.9. omega_model.context.mass_scaling module
Routines to load, validate, and provide access to vehicle mass scaling equation data
Mass scaling equations are defined by a mass term, a condition expression and equation to be evaluated.
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows.
The data represents vehicle mass scaling equations as a function of user-definable vehicle attributes or other conditions
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
mass_scaling
input_template_version:
0.1
- Sample Data Columns
mass_term
condition
equation
null_structure_mass_lbs
vehicle.body_style == ‘sedan’ and vehicle.unibody_structure==1
18.5 * vehicle.footprint_ft2 + 180
structure_mass_lbs
vehicle.structure_material == ‘steel’
1 * null_structure_mass
battery_mass_lbs
vehicle.powertrain_type == ‘BEV’
(2.2 * battery_kwh) / (0.0000000847 * battery_kwh ** 3 + 0.0000249011 * battery_kwh ** 2 + 0.0023686408 * battery_kwh + 0.1245668155)
powertrain_mass_lbs
vehicle.powertrain_type == ‘ICE’ and vehicle.drive_system==2
0.6 * vehicle.eng_rated_hp + 200
Data Column Name and Description
- mass_term:
Name of the mass term
- condition:
A boolean condition, which when
True
causes the evaluation of the following equation- equation:
The numeric equation which calculates the mass term
CODE
- class MassScaling
Bases:
OMEGABase
Load and provides routines to access mass scaling terms and equations.
- structure_materials = []
- static calc_mass_terms(vehicle, structure_material, eng_rated_hp, battery_kwh, footprint_ft2)
Calculate struture mass, battery mass and powertrain mass for the given vehicle
- Parameters:
vehicle (Vehicle) – the vehicle to calculate mass terms for
structure_material (str) – e.g. ‘steel’
eng_rated_hp (float) – engine rated horsepower
battery_kwh (float) – battery pack size in kWh
footprint_ft2 (float) – vehicle footpring in square feet
- Returns:
tuple of structure_mass_lbs, battery_mass_lbs, powertrain_mass_lbs, delta_glider_non_structure_mass_lbs, and usable_battery_capacity_norm for the given vehicle
- static init_from_file(filename, verbose=False)
Initialize class data from input file.
- Parameters:
filename (str) – name of input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
7.3.1.3.10. omega_model.context.new_vehicle_market module
Routines to load, access, and save new vehicle market data from/relative to the analysis context
Market data includes total sales as well as sales by context size class (e.g. ‘Small Crossover’)
This module also saves new vehicle generalized costs (based in part on OMEGA tech costs) from the reference session corresponding to the analysis context. The reference session vehicle sales (new vehicle market) will follow the analysis context sales, but prices/generalized costs within OMEGA will be different from prices within the context due to differences in costing approaches, etc. By saving the sales-weighted new vehicle generalized costs from the reference session, subsequent sessions (with higher, lower, or the same costs) will have an internally consistent (lower, higher or the same, respectively) overall sales response. Whether the vehicle generalized costs file will be loaded from a file or created from scratch is controlled by the batch process. Generally speaking, best practice is to always auto-generate the new vehicle generalized costs file from the reference session to guarantee consistency with the simulated vehicles file costs and all other factors affecting generalized cost (such as fuel prices, cost years, etc).
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows.
The data represents vehicle sales broken out by size class and regulatory class for each year of data for various context cases. Some size classes are represented in more than one regulatory class, some are not.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
context_new_vehicle_market
input_template_version:
0.22
[other]
- Sample Data Columns
context_id
dollar_basis
case_id
context_size_class
body_style
calendar_year
reg_class_id
sales_share_of_body_style
sales_share_of_regclass
sales_share_of_total
sales
weight_lbs
horsepower
horsepower_to_weight_ratio
mpg_conventional
mpg_conventional_onroad
mpg_alternative
mpg_alternative_onroad
onroad_to_cycle_mpg_ratio
ice_price_dollars
bev_price_dollars
AEO2020
2019
Reference case
Minicompact
sedan_wagon
2019
car
0.56
0.42
0.19
30958.782039697202
2938.287598
266.538513
0.09071219344948549
32.889961
26.858435502015
57.07032
46.6044793668
0.816615
76875.038
0.0
AEO2020
2019
Reference case
Subcompact
sedan_wagon
2019
car
6.1
4.52
2.11
331827.2822319624
3315.591309
263.971893
0.07961532903149494
33.923519
27.702454468185
49.373997
40.319546560155004
0.816615
40670.395
0.0
- Data Column Name and Description
- context_id:
The name of the context source, e.g. ‘AEO2020’, ‘AEO2021’, etc
- dollar_basis:
The dollar basis of any monetary values taken from the given AEO version.
- case_id:
The name of the case within the context, e.g. ‘Reference Case’, ‘High oil price’, etc
- context_size_class:
The name of the vehicle size class, e.g. ‘Minicompact’, ‘Large Utility’, etc
- body_style:
The name of the vehicle body style, e.g., ‘sedan_wagon’, ‘cuv_suv_van’, ‘pickup’
- calendar_year:
The calendar year of the vehicle market data
- reg_class_id:
The regulatory class of the vehicle data (within the context, reg class definitions may differ across years within the simulation based on policy changes.
reg_class_id
can be considered a ‘historical’ or ‘legacy’ reg class.- sales_share_of_body_style:
Sales share of the size class within its body style
- sales_share_of_regclass:
Sales share of the size class within its regulatory class
- sales_share_of_total:
Sales share of the total vehicle sales
- sales:
Number of vehicles sold of the size class
- weight_lbs:
Sales weighted average vehicle weight (pounds) of the size class
- horsepower:
Sales weighted average vehicle power (horsepower) of the size class
- horsepower_to_weight_ratio:
Sales weighted average vehicle power to weight ratio (horsepower/pound) of the size class
- mpg_conventional:
Sales weighted average certification fuel economy (miles per gallon, MPG)
- mpg_conventional_onroad:
Sales weighted average in-use fuel economy (miles per gallon, MPG), lower than the certification fuel economy by the
onroad_to_cycle_mpg_ratio
- mpg_alternative:
Sales weighted average battery electric certification fuel economy (miles per gallon equivalent, MPGe)
- mpg_alternative_onroad:
Sales weighted average battery electric in-use fuel economy (miles per gallon equivalent, MPGe)
- onroad_to_cycle_mpg_ratio:
The ratio of in-use to certification fuel economy
- ice_price_dollars:
Sales weighted average internal combustion engine (ICE) vehicle price (dollars)
- bev_price_dollars:
Sales weighted average battery electric vehicle (BEV) vehicle price (dollars)
CODE
- class NewVehicleMarket
Bases:
OMEGABase
Loads, provides access to and saves new vehicle market data from/relative to the analysis context
For each calendar year, context total vehicle sales are broken down by size class, with one row for each unique combination of size class and reg class.
- context_based_total_sales = {}
dict of context-based total sales by calendar year
- context_size_class_info_by_nrmc = {}
information about which context size classes are in which non-responsive market categories as well as what share of the size class is within the non-responsive category. Populated by vehicles.py in Vehicle.init_vehicles_from_file()
- Type:
dict of dicts
- base_year_context_size_class_sales = {}
sales totals for each context size class represented in the base year vehicles input file (e.g ‘vehicles.csv’). Populated by vehicles.py in Vehicle.init_vehicles_from_file()
- Type:
dict
- base_year_other_sales = {}
sales totals by other categories represented in the base year vehicles input file (e.g ‘vehicles.csv’). Populated by vehicles.py in Vehicle.init_vehicles_from_file()
- Type:
dict
- manufacturer_base_year_sales_data = {}
sales totals by various categories by manufacturer represented in the base year vehicles input file (e.g ‘vehicles.csv’). Populated by vehicles.py in Vehicle.init_vehicles_from_file()
- Type:
dict
- context_size_classes = []
- context_ids = []
- context_case_ids = []
- classmethod init_context_new_vehicle_generalized_costs(filename)
Load context new vehicle prices from file or clear _context_new_vehicle_generalized_costs and start from scratch. Clears _session_new_vehicle_generalized_costs.
- Parameters:
filename (str) – name of file to load new vehicle generalized costs from if not generating a new one
- classmethod save_context_new_vehicle_generalized_costs(filename)
Save context_new_vehicle_generalized_costs to a .csv file
- Parameters:
filename (str) – name of file to save new vehicle generalized costs to
- classmethod save_session_new_vehicle_generalized_costs(filename)
Save context_new_vehicle_generalized_costs to a .csv file
- Parameters:
filename (str) – name of file to save new vehicle generalized costs to
- classmethod get_context_new_vehicle_generalized_cost(calendar_year, compliance_id)
Get sales-weighted new vehicle generalized cost for a given year, in OMEGA-centric dollars
- Parameters:
calendar_year (numeric) – calendar year
compliance_id (str) – manufacturer name, or ‘consolidated_OEM’
- Returns:
OMEGA-centric context new vehicle generalized cost for the given calendar year
- classmethod set_context_new_vehicle_generalized_cost(calendar_year, compliance_id, generalized_cost)
Store new vehicle generalized cost for the given calendar year
- Parameters:
calendar_year (numeric) – calendar year
compliance_id (str) – manufacturer name, or ‘consolidated_OEM’
generalized_cost (float) – total sales-weighted OMEGA-centric generalized cost for the calendar year
- classmethod set_session_new_vehicle_generalized_cost(calendar_year, compliance_id, generalized_cost)
Store new vehicle generalized cost for the given calendar year
- Parameters:
calendar_year (numeric) – calendar year
compliance_id (str) – manufacturer name, or ‘consolidated_OEM’
generalized_cost (float) – total sales-weighted OMEGA-centric generalized cost for the calendar year
- static new_vehicle_data(calendar_year, context_size_class=None, context_reg_class=None, context_body_style=None, value='sales')
Get new vehicle sales by session context ID, session context case, calendar year, context size class and context reg class. User can specify total sales (no optional arguments) or sales by context size class or sales by context size class and context reg class depending on the arguments provided
- Parameters:
calendar_year (numeric) – calendar year
context_size_class (str | None) – optional context size class, e.g. ‘Small Crossover’
context_reg_class (str | None) – optional context reg class, e.g. ‘car’ or ‘truck’
context_body_style (str | None) – e.g. ‘sedan_wagon’
value (str) – the column name of the context value to sum
- Returns:
new vehicle total sales or sales by context size class or by context size class and reg class
Examples
total_new_vehicle_sales_2030 = ContextNewVehicleMarket.new_vehicle_sales(2030) small_crossover_new_vehicle_sales_2030 = ContextNewVehicleMarket.new_vehicle_sales(2030, context_size_class='Small Crossover') small_crossover_car_new_vehicle_sales_2030 = ContextNewVehicleMarket.new_vehicle_sales(2030, context_size_class='Small Crossover', context_reg_class='car')
- static validate_context_size_class(context_size_class)
Validate the given context size class
- Parameters:
context_size_class (str) – e.g. ‘Large Pickup’, etc
- Returns:
True
if the given context size class name is valid,False
otherwise
- static validate_context_id(context_id)
Validate the given context ID
- Parameters:
context_id (str) – e.g. ‘Reference case’, etc
- Returns:
True
if the given context ID name is valid,False
otherwise
- static validate_case_id(case_id)
Validate the given case ID
- Parameters:
case_id (str) – e.g. ‘AEO2021’, etc
- Returns:
True
if the given case ID name is valid,False
otherwise
- static get_context_size_class_mpg(size_class, reg_class_id, year, onroad=True)
- Parameters:
size_class (str) – the context_size_class, e.g., “Subcompact”, “Large Van”
reg_class_id (str) – e.g., “car”, “truck”
year (int) – the calendar year of new vehicles (i.e., the model year for age=0)
onroad (bool) – onroad miles per gallon if True; cycle if False
Returns:
- static init_from_file(filename, verbose=False)
Initialize class data from input file.
- Parameters:
filename (str) – name of input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
7.3.1.3.11. omega_model.context.onroad_fuels module
Routines to load and retrieve onroad (in-use) fuel attribute data
Fuel data includes a name, units (e.g. gallons, kWh), CO2e g/unit, refuel_efficiency and transmission_efficiency.
See also
vehicles
and context_fuel_prices
modules, and consumer
subpackage
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows.
The data represents fuel property data for on-road/in-use purposes.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
onroad-fuels
input_template_version:
0.1
- Sample Data Columns
fuel_id
start_year
unit
direct_co2e_grams_per_unit
refuel_efficiency
transmission_efficiency
pump gasoline
2020
gallon
8887
1
1
US electricity
2020
kWh
0
0.9
0.935
Data Column Name and Description
- fuel_id:
The Fuel ID, as referenced by the
vehicles
andcontext_fuel_prices
modules, andconsumer
subpackage.- start_year:
Start year of fuel properties, properties apply until the next available start year
- unit:
Fuel unit, e.g. ‘gallon’, ‘kWh’
- direct_co2e_grams_per_unit:
CO2e emissions per unit when consumed
- refuel_efficiency:
Refuel efficiency [0..1], e.g. electrical vehicle charging efficiency
- transmission_efficiency:
Fuel transmission efficiency [0..1], e.g. electrical grid efficiency, may also be referred to as “grid loss”
CODE
- class OnroadFuel
Bases:
OMEGABase
Loads and provides methods to access onroad fuel attribute data.
- fuel_ids = []
- kilowatt_hours_per_gallon = 33.7
- grams_co2e_per_gallon = 8887
- static get_fuel_attribute(calendar_year, in_use_fuel_id, attribute)
- Parameters:
calendar_year (numeric) – year to get fuel properties in
in_use_fuel_id (str) – e.g. ‘pump gasoline’)
attribute (str) – name of attribute to retrieve
- Returns:
Fuel attribute value for the given year.
Example
carbon_intensity_gasoline = OnroadFuel.get_fuel_attribute(2020, 'pump gasoline', 'direct_co2e_grams_per_unit')
- static init_from_file(filename, verbose=False)
Initialize class data from input file.
- Parameters:
filename (str) – name of input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
7.3.1.3.12. omega_model.context.powertrain_cost_frm module
Routines to calculate powertrain cost.
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows. The template header uses a dynamic format.
- File Type
comma-separated values (CSV)
- Template Header
input_template_name:
[module_name]
input_template_version:
[template_version]
[other]
- Sample Header
input_template_name:
context.powertrain_cost_frm
input_template_version:
0.21
description:
Same as 20231128, and with slower rampin of Battery Offset for 45X, 0.5 0.75 and 1 in 2023 2030 and 2032
- Sample Data Columns
powertrain_type
powertrain_subtype
system
subsystem
drive_system
engine_configuration
body_style
value
dollar_basis
Formula Notes
Notes
BEV
Drive_Unit
Gearbox
RWD
sedan
281.00 * MARKUP_BEV
2022
FEV single_speed_gearbox_dual
HEV
Electrical_Power_Supply
DC_DC_Converter
250 * MARKUP_HEV
2022
FEV
ICE
Engine
EGR
pickup
100 * MARKUP_ICE
2022
FEV
PHEV
Engine
VVT
V
sedan
200 * MARKUP_ICE
2022
FEV
ALL
Exhaust
gpf
(42.269 * LITERS + 22.213) * MARKUP_ICE
2022
from SB on 20231128
SME
Data Column Name and Description
- powertrain_type:
Vehicle powertrain type, e.g. ‘ICE’, ‘PHEV’, etc
- powertrain_subtype:
For Hybrids and Mild Hybrids, e.g. ‘P0’, ‘P2’, ‘PS’, etc
- system:
Vehicle system, e.g. ‘Engine’, ‘Exhaust’, ‘Driveline’, etc
- subsystem:
Vehicle subsystem, e.g. ‘DC_DC_Converter’, ‘EGR’, ‘HVAC’, etc
- drive_system:
Drive system type, e.g. ‘FWD’, ‘RWD’, ‘AWD’, etc
- engine_configuration:
‘I’ = inline cylinder engine, ‘V’ = v-type, non-inline cylinder engine
- body_style:
Body style, e.g. ‘sedan’, ‘pickup’, etc
- value:
The component cost value or equation to be evaulated
- dollar_basis:
The dollar basis year for the cost value, e.g.
2022
- Formula Notes:
Optional notes related to the formula
- Notes:
Optional notes related to the data row such as data source
CODE
- class PowertrainCost
Bases:
OMEGABase
Loads and provides access to powertrain cost data, provides methods to calculate powertrain costs.
- cost_tracker = {}
- static calc_cost(vehicle, powertrain_type=None, pkg_info=None, update_tracker=False)
Calculate the value of the response surface equation for the given powertrain type, cost curve class (tech package) for the full factorial combination of the iterable terms.
- Parameters:
powertrain_type (str) – e.g., ‘ICE’, ‘BEV’, ‘PHEV’, ‘HEV’
vehicle (Vehicle) – the vehicle to calc costs for
pkg_info (dict-like) – the necessary information for developing cost estimates.
update_tracker (bool) – update cost tracking dict if
True
- Returns:
A list of cost values indexed the same as pkg_df.
- static init_from_file(filename, verbose=False)
Initialize class data from input file.
- Parameters:
filename (str) – name of input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
- get_learning_factors(v, locals_dict, powertrain_type)
Get learning factors for use in estimating powertrain costs.
- Parameters:
v (Vehicle) – the Vehicle object
locals_dict (dict) – local attributes
powertrain_type (str) – e.g., ‘BEV’, ‘PHEV’, ‘HEV’
- Returns:
Learning factors for ICE, PEV, and high-voltage batteries for use in calculating powertrain costs; locals_dict is also returned with updated local attributes.
- get_markups(locals_dict)
Get markups for estimating indirect costs.
- Parameters:
locals_dict (dict) – local attributes
- Returns:
A list of markup factors for use with ICE, MHEV, HEV, PHEV and BEV technologies
- get_obc_power(pkg_info, powertrain_type)
Get the charging power of the onboard charger, if equipped.
- Parameters:
pkg_info (Series) – the necessary information for developing cost estimates
powertrain_type (str) – e.g., ‘ICE’, ‘BEV’, ‘PHEV’, ‘HEV’
- Returns:
The charging power of the onboard charger
- get_motor_power(locals_dict, pkg_info, powertrain_type, powertrain_subtype, drive_system)
Get the electric drive motor-power, if equipped, of the given package.
- Parameters:
locals_dict (dict) – local attributes
pkg_info (Series) – the necessary information for developing cost estimates
powertrain_type (str) – e.g., ‘ICE’, ‘BEV’, ‘PHEV’, ‘HEV’
powertrain_subtype (str) – e.g., ‘P0’, ‘P2’, ‘PS’
drive_system (str) – e.g., ‘FWD’, ‘RWD’, ‘AWD’ denoting front/rear/all wheel drive
- Returns:
The motive power of the electric drive motor(s) whether it be the primary drive unit, the front and rear drive units or the P2 and P4 drive units, depending on the package architecture
- get_powertrain_subtype(cost_curve_class)
- Parameters:
cost_curve_class (str) – the cost curve class of the package
- Returns:
The powertrain subtype, if applicable
- get_trans(pkg_info)
Get the transmission code for the given powertrain package.
- Parameters:
pkg_info (Series) – powertain package information
- Returns:
The transmission code for the given data.
- get_engine_deets(pkg_info)
Get engine details, if equipped, for the given powertrain package.
- Parameters:
pkg_info (Series) – powertain package information
- Returns:
The number of cylinders, the displacement (liters) and ‘I’ or ‘V’ configuration of the engine block.
- calc_gasoline_eas_cost(vehicle, locals_dict, learning_factor)
Calculate exhaust aftertreatment system (eas) costs for gasoline-fueled engines.
- Parameters:
vehicle (Vehicle) – the vehicle to calc costs for
locals_dict (dict) – local attributes
learning_factor (float) – the learning factor to use
- Returns:
The three-way catalyst (twc) substrate, washcoat, canning, platinum group metal (pgm) and total costs along with the gasoline particulate filter (gpf) cost
- calc_diesel_eas_cost(locals_dict, learning_factor)
Calculate exhaust aftertreatment system (eas) cost for diesel-fueled engines.
- Parameters:
locals_dict (dict) – local attributes
learning_factor (float) – the learning factor to use
- Returns:
The diesel exhaust aftertreatment system cost
- calc_non_eas_exhaust_cost(locals_dict, learning_factor, powertrain_type, engine_config, body_style)
Calculate non-eas exhaust system cost for all liquid-fueled engines.
- Parameters:
locals_dict (dict) – local attributes
learning_factor (float) – the learning factor to use
powertrain_type (str) – e.g., ‘ICE’, ‘BEV’, ‘PHEV’, ‘HEV’
engine_config (str) – e.g., ‘I’ or ‘V’ configuration of the engine block
body_style (str) – e.g., ‘sedan’, ‘cuv_suv’ or ‘pickup’
- Returns:
The exhaust system cost excluding the exhaust aftertreatment system (eas)
- calc_engine_cost(locals_dict, learning_factor, pkg_info, powertrain_type, engine_config, body_style, diesel_flag=False)
Calculate the cost of the engine, if equipped, including technologies included on the engine, if equipped (e.g., GDI, EGR, etc.).
- Parameters:
locals_dict (dict) – local attributes
learning_factor (float) – the learning factor to use
pkg_info (Series) – powertain package information
powertrain_type (str) – e.g., ‘ICE’, ‘BEV’, ‘PHEV’, ‘HEV’
engine_config (str) – e.g., ‘I’ or ‘V’ configuration of the engine block
body_style (str) – e.g., ‘sedan’, ‘cuv_suv’ or ‘pickup’
diesel_flag (bool) – True for diesel engines (default is False)
- Returns:
The engine block cost, cooled EGR cost, GDI cost, turbocharger cost, cylinder deactivation cost, and Atkinson-specific cost, all where applicable; costs are $0 where not applicable
- calc_fuel_storage_cost(locals_dict, learning_factor, powertrain_type, body_style)
Calculate the cost of the liquid-fuel storage on liquid-fueled vehicles.
- Parameters:
locals_dict (dict) – local attributes
learning_factor (float) – the learning factor to use
powertrain_type (str) – e.g., ‘ICE’, ‘BEV’, ‘PHEV’, ‘HEV’
body_style (str) – e.g., ‘sedan’, ‘cuv_suv’ or ‘pickup’
- Returns:
The fuel storage system cost for liquid-fueled vehicles
- calc_lv_battery_cost(locals_dict, learning_factor, powertrain_type)
Calculate the low voltage battery cost for all vehicles.
- Parameters:
locals_dict (dict) – local attributes
learning_factor (float) – the learning factor to use
powertrain_type (str) – e.g., ‘ICE’, ‘BEV’, ‘PHEV’, ‘HEV’
- Returns:
The low voltage battery cost
- calc_start_stop_cost(locals_dict, learning_factor, pkg_info)
Calculate the start-stop system cost, if equipped.
- Parameters:
locals_dict (dict) – local attributes
learning_factor (float) – the learning factor to use
pkg_info (Series) – powertain package information
- Returns:
The start-stop system cost
- calc_trans_cost(locals_dict, learning_factor, powertrain_type, powertrain_subtype, drive_system, body_style)
Calculate the transmission cost, if equipped, of the given package.
- Parameters:
locals_dict (dict) – local attributes
learning_factor (float) – the learning factor to use
powertrain_type (str) – e.g., ‘ICE’, ‘BEV’, ‘PHEV’, ‘HEV’
powertrain_subtype (str) – e.g., ‘P0’, ‘P2’, ‘PS’, ‘ALL’
drive_system (str) – e.g., ‘FWD’, ‘RWD’, ‘AWD’ denoting front/rear/all wheel drive
body_style (str) – e.g., ‘sedan’, ‘cuv_suv’, ‘pickup’
- Returns:
The transmission cost for the given package
Notes
Start-stop for non-electrified ICE is included in calc_start_stop_cost
- calc_motor_cost(locals_dict, learning_factor, powertrain_type, drive_system, body_style='-')
Calculate the electric drive motor cost, if equipped.
- Parameters:
locals_dict (dict) – local attributes
learning_factor (float) – the learning factor to use
powertrain_type (str) – e.g., ‘BEV’, ‘PHEV’, ‘HEV’
drive_system (str) – e.g., ‘FWD’, ‘RWD’, ‘AWD’ denoting front/rear/all wheel drive
body_style (str) – e.g., ‘sedan’, ‘cuv_suv’ or ‘pickup’
- Returns:
The electric drive motor cost, including all drive motors
- calc_high_efficiency_alternator(locals_dict, learning_factor, pkg_info)
Calculate the cost of the high efficiency alternator, if equipped.
- Parameters:
locals_dict (dict) – local attributes
learning_factor (float) – the learning factor to use
pkg_info (Series) – powertain package information
- Returns:
The high efficiency alternator cost
- calc_powertrain_cooling_cost(locals_dict, learning_factor, powertrain_type, drive_system, engine_config, body_style)
Calculate the powertrain thermal control system cost for all vehicles.
- Parameters:
locals_dict (dict) – local attributes
learning_factor (float) – the learning factor to use
powertrain_type (str) – e.g., ‘ICE’, ‘BEV’, ‘PHEV’, ‘HEV’
drive_system (str) – e.g., ‘FWD’, ‘RWD’, ‘AWD’ denoting front/rear/all wheel drive
engine_config (str) – e.g., ‘I’ or ‘V’ configuration of the engine block
body_style (str) – e.g., ‘sedan’, ‘cuv_suv’ or ‘pickup’
- Returns:
The powertrain thermal control system cost
- calc_hvac_cost(locals_dict, learning_factor, powertrain_type)
Calculate the powertrain thermal control system cost for all vehicles.
- Parameters:
locals_dict (dict) – local attributes
learning_factor (float) – the learning factor to use
powertrain_type (str) – e.g., ‘ICE’, ‘BEV’, ‘PHEV’, ‘HEV’
- Returns:
The HVAC system cost
- calc_air_conditioning_costs(locals_dict, learning_factor)
Calculate the air conditioning (ac) system costs for all vehicles.
- Parameters:
locals_dict (dict) – local attributes
learning_factor (float) – the learning factor to use
- Returns:
The ac-leakage and ac-efficiency costs
- calc_lv_harness_cost(locals_dict, learning_factor, powertrain_type, drive_system, body_style)
Calculate the low voltage harness cost for all vehicles.
- Parameters:
locals_dict (dict) – local attributes
learning_factor (float) – the learning factor to use
powertrain_type (str) – e.g., ‘ICE’, ‘BEV’, ‘PHEV’, ‘HEV’
drive_system (str) – e.g., ‘FWD’, ‘RWD’, ‘AWD’ denoting front/rear/all wheel drive
body_style (str) – e.g., ‘sedan’, ‘cuv_suv’ or ‘pickup’
- Returns:
The low voltage harness cost
- calc_hv_harness_cost(locals_dict, learning_factor, powertrain_type, drive_system, body_style)
Calculate the high voltage harness cost, if equipped.
- Parameters:
locals_dict (dict) – local attributes
learning_factor (float) – the learning factor to use
powertrain_type (str) – e.g., ‘BEV’, ‘PHEV’, ‘HEV’
drive_system (str) – e.g., ‘FWD’, ‘RWD’, ‘AWD’ denoting front/rear/all wheel drive
body_style (str) – e.g., ‘sedan’, ‘cuv_suv’ or ‘pickup’
- Returns:
The high voltage harness cost
- calc_dc_dc_converter_cost(locals_dict, learning_factor, powertrain_type)
Calculate the DC-to-DC converter cost, if equipped.
- Parameters:
locals_dict (dict) – local attributes
learning_factor (float) – the learning factor to use
powertrain_type (str) – e.g., ‘BEV’, ‘PHEV’, ‘HEV’
- Returns:
The DC-to-DC converter cost
Notes
The OBC kW is determined in the get_obc_power function.
- calc_charge_cord_cost(locals_dict, learning_factor, powertrain_type)
Calculate the external charging device cost, if equipped.
- Parameters:
locals_dict (dict) – local attributes
learning_factor (float) – the learning factor to use
powertrain_type (str) – e.g., ‘BEV’, ‘PHEV’
- Returns:
The external charging device cost
- calc_inverter_cost(locals_dict, learning_factor, powertrain_type, powertrain_subtype='-', drive_system='-', body_style='-')
Calculate the costs for inverters on BEVs and on electrified AWD.
- Parameters:
locals_dict (dict) – local attributes
learning_factor (float) – the learning factor to use
powertrain_type (str) – e.g., ‘BEV’, ‘PHEV’, ‘HEV’
powertrain_subtype (str) – e.g., ‘P0’, ‘P2’, ‘PS’
drive_system (str) – e.g., ‘FWD’, ‘RWD’, ‘AWD’
body_style (str) – e.g., ‘P0’, ‘P2’, ‘PS’
- Returns:
The inverter cost(s)
- calc_gearbox_cost(locals_dict, learning_factor, powertrain_type, body_style, powertrain_subtype='-', drive_system='AWD')
Calculate the costs for gearboxes on BEVs.
- Parameters:
locals_dict (dict) – local attributes
learning_factor (float) – the learning factor to use
powertrain_type (str) – e.g., ‘BEV’, ‘PHEV’, ‘HEV’
powertrain_subtype (str) – e.g., ‘P0’, ‘P2’, ‘PS’
drive_system (str) – e.g., ‘FWD’, ‘RWD’, ‘AWD’ denoting front/rear/all wheel drive
body_style (str) – e.g., ‘sedan’, ‘cuv_suv’ or ‘pickup’
- Returns:
The gearbox(es) cost
- calc_battery_cost(locals_dict, learning_factor, powertrain_type, model_year)
Calculate the high voltage battery pack cost on electrified vehicles.
- Parameters:
locals_dict (dict) – local attributes
learning_factor (float) – the learning factor to use
powertrain_type (str) – e.g., ‘BEV’, ‘PHEV’, ‘HEV’
model_year (int) – the model year of the vehicle
- Returns:
The high voltage battery pack cost
- calc_battery_offset(locals_dict, v, powertrain_type, battery_kwh)
Calculate the high voltage battery pack cost offset, where applicable (e.g., pursuant to the Inflation Reduction Act).
- Parameters:
locals_dict (dict) – local attributes
v (Vehicle) – the Vehicle object
powertrain_type (str) – e.g., ‘BEV’, ‘PHEV’
battery_kwh (float) – battery pack gross capacity, kWh
- Returns:
The high voltage battery pack cost offset
7.3.1.3.13. omega_model.context.powertrain_cost_nprm module
Routines to calculate powertrain cost.
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows. The template header uses a dynamic format.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
powertrain_cost
input_template_version:
0.1
{optional_source_data_comment}
- Sample Data Columns
powertrain_type
item
value
quantity
dollar_basis
notes
ALL
dollars_per_cylinder
((-28.814) * CYL + 726.27) * CYL * MARKUP_ICE
2019
ALL
dollars_per_liter
((400) * LITERS) * MARKUP_ICE
2019
ALL
gdi
((43.237) * CYL + 97.35) * MARKUP_ICE
2019
BEV
battery_offset
{“dollars_per_kwh”: {2023: -9
2024: -18
2025: -27
2026: -36
2027: -45
2028: -45
2029: -45
2030: -33.75
2031: -22.50
2032: -11.25
2033: -0}}
Data Column Name and Description
- powertrain_type:
Vehicle powertrain type, e.g. ‘ICE’, ‘PHEV’, etc
- item:
The name of the powertrain component associated with the cost value
- value:
The component cost value or equation to be evaulated
- quantity:
Component quantity per vehicle, if applicable
- dollar_basis:
The dollar basis year for the cost value, e.g.
2020
- notes:
Optional notes related to the data row
CODE
- class PowertrainCost
Bases:
OMEGABase
Loads and provides access to powertrain cost data, provides methods to calculate powertrain costs.
- cost_tracker = {}
- static calc_cost(vehicle, powertrain_type=None, pkg_info=None, update_tracker=False)
Calculate the value of the response surface equation for the given powertrain type, cost curve class (tech package) for the full factorial combination of the iterable terms.
- Parameters:
powertrain_type (str) – e.g., ‘ICE’, ‘BEV’, ‘PHEV’, ‘HEV’, ‘MHEV’
vehicle (Vehicle) – the vehicle to calc costs for
pkg_info (dict-like) – the necessary information for developing cost estimates.
update_tracker (bool) – update cost tracking dict if
True
- Returns:
A list of cost values indexed the same as pkg_df.
- static init_from_file(filename, verbose=False)
Initialize class data from input file.
- Parameters:
filename (str) – name of input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
- get_trans(pkg_info)
Get the transmission code for the given powertrain package.
- Parameters:
pkg_info (Series) – powertain package information
- Returns:
The transmission code for the given data.
7.3.1.3.14. omega_model.context.price_modifications module
Code to implement (non-EPA-policy) price modifications, which may be price reductions or increases.
An example price modification would be BEV rebates. Price modifications are by market class ID and year.
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows. The data header uses a dynamic column notation, as detailed below.
The data represents price modifications by market class ID and start year.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
vehicle_price_modifications
input_template_version:
0.2
The data header consists of a start_year
column followed by zero or more price modification columns.
- Dynamic Data Header
start_year
{market_class_id}:price_modification_dollars
…
- Sample Data Columns
start_year
sedan_wagon.BEV:price_modification_dollars
cuv_suv_van.BEV:price_modification_dollars
pickup.BEV:price_modification_dollars
2020
-7500
-5000
0
Data Column Name and Description
- start_year:
Start year of price modification, modification applies until the next available start year
Optional Columns
{market_class_id}:price_modification_dollars
:Contains the price modification. Value should be negative to reduce price, positive to increase price.
CODE
- class PriceModifications
Bases:
OMEGABase
Loads and provides access to price modification data by model year and market class ID.
- static get_price_modification(calendar_year, market_class_id)
Get the price modification (if any) for the given year and market class ID.
- Parameters:
calendar_year (int) – calendar year to get price modification for
market_class_id (str) – market class id, e.g. ‘hauling.ICE’
- Returns:
The requested price modification, or 0 if there is none.
- static init_from_file(filename, verbose=False)
Initialize class data from input file.
- Parameters:
filename (str) – name of input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
7.3.1.3.15. omega_model.context.production_constraints module
Code to load and implement production constraints by market class and year.
Market classes are assumed to have no minimum or maximum constraint unless specified in the input file, and it is only necessary to specify the limiting constraints, i.e. a minimum can be specified without specifying a maximum, and vice versa.
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows. The data header uses a dynamic column notation, as detailed below.
The data represents production constraints (specified as a market share) by market class ID and start year. Shares are relative to the market category, not absolute.
- File Type
comma-separated values (CSV)
The data header consists of a start_year
column followed by zero or more production constraint columns.
- Dynamic Data Header
start_year
{market_class_id}:{minimum_share or maximum_share}
…
- Sample Header
input_template_name:
production_constraints
input_template_version:
0.2
- Sample Data Columns
start_year
sedan_wagon.BEV:minimum_share
cuv_suv_van.BEV:minimum_share
pickup.BEV:minimum_share
sedan_wagon.BEV:maximum_share
cuv_suv_van.BEV:maximum_share
pickup.BEV:maximum_share
2020
0
0
0
1
1
1
Data Column Name and Description
- start_year:
Start year of production constraint, constraint applies until the next available start year
Optional Columns
{market_class_id}:{minimum_share or maximum_share}
:Holds the value of the minimum or maximum production constraint, as required, [0..1]
CODE
- class ProductionConstraints
Bases:
OMEGABase
Loads and provides access to production constraint data.
Get the minimum possible market share for the given calendar year and market class ID
- Parameters:
calendar_year (int) – calendar year to get minimum production constraint for
market_class_id (str) – market class id, e.g. ‘hauling.ICE’
- Returns:
The minimum production share for the given year and market class ID
See also
producer.compliance_strategy.create_tech_and_share_sweeps()
Get the maximum possible market share for the given calendar year and market class ID
- Parameters:
calendar_year (int) – calendar year to get maximum production constraint for
market_class_id (str) – market class id, e.g. ‘hauling.ICE’
- Returns:
The maximum production share for the given year and market class ID
See also
producer.compliance_strategy.create_tech_and_share_sweeps()
- static init_from_file(filename, verbose=False)
Initialize class data from input file.
- Parameters:
filename (str) – name of input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
7.3.1.3.16. omega_model.context.rse_cost_clouds module
Routines to create simulated vehicle data (vehicle energy/CO2e consumption, off-cycle tech application, and cost data) and calculate frontiers from response surface equations fitted to vehicle simulation results
Cost cloud frontiers are at the heart of OMEGA’s optimization and compliance processes. For every set of points represented in $/CO2e_g/mi (or Y versus X in general) there is a set of points that represent the lowest cost for each CO2e level, this is referred to as the frontier of the cloud. Each point in the cloud (and on the frontier) can store multiple parameters, implemented as rows in a pandas DataFrame where each row can have multiple columns of data.
Each manufacturer vehicle, in each model year, gets its own frontier. The frontiers are combined in a sales-weighted fashion to create composite frontiers for groups of vehicles that can be considered simultaneously for compliance purposes. These groups of vehicles are called composite vehicles (see also vehicles.py, class CompositeVehicle). The points of the composite frontiers are in turn combined and sales-weighted in various combinations during manufacturer compliance search iteration.
Frontiers can hew closely to the points of the source cloud or can cut through a range of representative points
depending on the value of o2.options.cost_curve_frontier_affinity_factor
. Higher values pick up more points, lower
values are a looser fit. The default value provides a good compromise between number of points and accuracy of fit.
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows. The template header uses a dynamic format.
The data represents vehicle technology options and costs by simulation class (cost curve class) and model year.
- File Type
comma-separated values (CSV)
- Template Header
input_template_name:
[module_name]
input_template_version:
[template_version]
- Sample Header
input_template_name:
context.rse_cost_clouds
input_template_version:
0.21
- Sample Data Columns
cost_curve_class
cs_ftp_1:cert_direct_oncycle_co2e_grams_per_mile
cs_ftp_2:cert_direct_oncycle_co2e_grams_per_mile
cs_ftp_3:cert_direct_oncycle_co2e_grams_per_mile
cs_hwfet:cert_direct_oncycle_co2e_grams_per_mile
cs_us06_1:cert_direct_oncycle_co2e_grams_per_mile
cs_us06_2:cert_direct_oncycle_co2e_grams_per_mile
engine_displacement_liters
engine_cylinders
hev_motor_kw
hev_batt_kwh
unibody
high_eff_alternator
start_stop
mhev
hev
hev_truck
deac_pd
deac_fc
cegr
atk2
gdi
turb12
turb11
gas_fuel
diesel_fuel
awd
fwd
trx10
trx11
trx12
trx21
trx22
ecvt
ice
fcv
phev
GDI_TRX10_SS0
(18.5453154586108 + RLHP20 * -3982.40242855764 + RLHP60 * -2817.56800285645 + HP_ETW * 137.278361090642 + ETW * 3.32340903920597E-02 + RLHP20 * RLHP60 * 110807.33630121 + RLHP20 * HP_ETW * -4627.4326168311 + RLHP20 * ETW * 6.70966614616728 + RLHP60 * HP_ETW * -30332.4612603004 + RLHP60 * ETW * 5.00876531603704 + HP_ETW * ETW * 0.294125190164327 + RLHP20 * RLHP20 * 1256197.72766571 + RLHP60 * RLHP60 * 481695.350341595 + HP_ETW * HP_ETW * 1609.12975282719 + ETW * ETW * -8.29944026819907E-08)
(9.5791054371677 + RLHP20 * -3590.79375495996 + RLHP60 * 50.6722067942342 + HP_ETW * 347.705321630021 + ETW * 3.48152635650444E-02 + RLHP20 * RLHP60 * 149496.500686564 + RLHP20 * HP_ETW * -2223.94352321471 + RLHP20 * ETW * 9.48200087525242 + RLHP60 * HP_ETW * 2351.5654615553 + RLHP60 * ETW * 0.461922645205613 + HP_ETW * ETW * 0.471412910808918 + RLHP20 * RLHP20 * 1436117.83181053 + RLHP60 * RLHP60 * 39270.700829774 + HP_ETW * HP_ETW * 406.447384354043 + ETW * ETW * -7.71706080556899E-08)
(16.90268475641 + RLHP20 * -3242.90634919696 + RLHP60 * -2629.28146207688 + HP_ETW * 118.975915082563 + ETW * 2.89017033343035E-02 + RLHP20 * RLHP60 * 92250.9850799915 + RLHP20 * HP_ETW * -4113.71943103567 + RLHP20 * ETW * 5.80112048232174 + RLHP60 * HP_ETW * -26327.5543378143 + RLHP60 * ETW * 4.36516119956593 + HP_ETW * ETW * 0.257209252731031 + RLHP20 * RLHP20 * 1079137.01783225 + RLHP60 * RLHP60 * 434252.441619121 + HP_ETW * HP_ETW * 1393.97146449451 + ETW * ETW * -7.30125392390274E-08)
(17.9637457539001 + RLHP20 * -3472.62459269551 + RLHP60 * -4398.38499132763 + HP_ETW * 215.768640351807 + ETW * 8.51144457518359E-03 + RLHP20 * RLHP60 * 149970.005773222 + RLHP20 * HP_ETW * -21981.6870797447 + RLHP20 * ETW * 3.63778043662855 + RLHP60 * HP_ETW * -59423.2422059756 + RLHP60 * ETW * 8.04728064311791 + HP_ETW * ETW * 7.86039589271401E-02 + RLHP20 * RLHP20 * 848749.589907981 + RLHP60 * RLHP60 * 616072.465286428 + HP_ETW * HP_ETW * 2979.55595160764 + ETW * ETW * -1.4351363539333E-08)
(9.56569818390454 + RLHP20 * 6596.09179395163 + RLHP60 * -613.085872919802 + HP_ETW * -318.90997967565 + ETW * 0.101983529095103 + RLHP20 * RLHP60 * 2170002.03346542 + RLHP20 * HP_ETW * -64249.5598973361 + RLHP20 * ETW * 2.75914558215585 + RLHP60 * HP_ETW * -44733.8189080356 + RLHP60 * ETW * 4.62964787308715 + HP_ETW * ETW * -3.71755481566662E-02 + RLHP20 * RLHP20 * -2853471.14537167 + RLHP60 * RLHP60 * 128583.11933152 + HP_ETW * HP_ETW * 7854.33640825238 + ETW * ETW * 1.26205572300569E-07)
(41.1164896514876 + RLHP20 * 2234.44390496137 + RLHP60 * -22070.3587003615 + HP_ETW * 610.147530710725 + ETW * 1.28797324323515E-02 + RLHP20 * RLHP60 * -728006.913610047 + RLHP20 * HP_ETW * 46152.9690756253 + RLHP20 * ETW * -2.88589393142033 + RLHP60 * HP_ETW * -118593.147293144 + RLHP60 * ETW * 15.9274202719561 + HP_ETW * ETW * -3.60173610138859E-02 + RLHP20 * RLHP20 * -309499.872474524 + RLHP60 * RLHP60 * 2587604.52877069 + HP_ETW * HP_ETW * 1551.30184056957 + ETW * ETW * 5.53256211916988E-08)
(9.42426552897976E-02 + RLHP20 * -8.67753548243127 + RLHP60 * -1.25433074169979 + HP_ETW * 2.36155977722839 + ETW * -5.02570130409737E-05 + RLHP20 * RLHP60 * -1346.72585688432 + RLHP20 * HP_ETW * -2.01875340702074 + RLHP20 * ETW * -2.86900770294598E-04 + RLHP60 * HP_ETW * -9.79248304114116 + RLHP60 * ETW * -8.02462001216872E-04 + HP_ETW * ETW * 1.31800222688058E-02 + RLHP20 * RLHP20 * 4522.82437754836 + RLHP60 * RLHP60 * 862.766253485694 + HP_ETW * HP_ETW * -14.9086015192973 + ETW * ETW * 4.04706726926766E-09)
(-4.82637156703734 + RLHP20 * -105.074481298302 + RLHP60 * 54.2696982370053 + HP_ETW * 151.462510854908 + ETW * 0.00130625681466241 + RLHP20 * RLHP60 * -10076.0711025307 + RLHP20 * HP_ETW * 261.577105272997 + RLHP20 * ETW * -0.010298721021474 + RLHP60 * HP_ETW * -4.07581237442843 + RLHP60 * ETW * -0.0209676757797716 + HP_ETW * ETW * -0.00296283965731266 + RLHP20 * RLHP20 * 47916.0507236993 + RLHP60 * RLHP60 * 6235.77804094256 + HP_ETW * HP_ETW * -581.199529326768 + ETW * ETW * -4.05477867514449E-08)
0
0
1
0
0
0
0
0
0
0
0
0
1
0
0
1
0
0
1
1
0
0
0
0
0
1
0
0
GDI_TRX10_SS1
(17.3945556524814 + RLHP20 * -3678.93129741256 + RLHP60 * -3049.38693353786 + HP_ETW * 67.2832031730545 + ETW * 3.28941003129913E-02 + RLHP20 * RLHP60 * 109636.473272387 + RLHP20 * HP_ETW * -5729.03684895062 + RLHP20 * ETW * 6.69010202922273 + RLHP60 * HP_ETW * -30027.6511414333 + RLHP60 * ETW * 5.03102604096674 + HP_ETW * ETW * 0.253718771476502 + RLHP20 * RLHP20 * 1204537.81741955 + RLHP60 * RLHP60 * 493584.495898655 + HP_ETW * HP_ETW * 1931.96067256056 + ETW * ETW * -8.00143560878314E-08)
(6.09111677491136 + RLHP20 * -3081.94312700559 + RLHP60 * -26.3676295610723 + HP_ETW * 237.351389156045 + ETW * 3.45305581858264E-02 + RLHP20 * RLHP60 * 198197.59303984 + RLHP20 * HP_ETW * -4158.45730287789 + RLHP20 * ETW * 9.43126927729562 + RLHP60 * HP_ETW * 2678.06741551965 + RLHP60 * ETW * 0.472345818320218 + HP_ETW * ETW * 0.405183157861073 + RLHP20 * RLHP20 * 1270438.81851366 + RLHP60 * RLHP60 * 33613.6602886178 + HP_ETW * HP_ETW * 1029.38089977022 + ETW * ETW * -8.55268065109595E-08)
(15.2414651650666 + RLHP20 * -3140.68640670414 + RLHP60 * -2688.84923545992 + HP_ETW * 42.788916424425 + ETW * 2.85968485885624E-02 + RLHP20 * RLHP60 * 102784.268828302 + RLHP20 * HP_ETW * -5382.85950863125 + RLHP20 * ETW * 5.78794685887964 + RLHP60 * HP_ETW * -26055.7046118476 + RLHP60 * ETW * 4.38225109623388 + HP_ETW * ETW * 0.212795915443702 + RLHP20 * RLHP20 * 1051240.4750741 + RLHP60 * RLHP60 * 430073.482368004 + HP_ETW * HP_ETW * 1758.43536857247 + ETW * ETW * -7.31926954156259E-08)
(18.0397672059242 + RLHP20 * -3458.63617341381 + RLHP60 * -4434.1760180141 + HP_ETW * 214.730811606447 + ETW * 8.48047223497087E-03 + RLHP20 * RLHP60 * 141263.645257291 + RLHP20 * HP_ETW * -21996.5452273929 + RLHP20 * ETW * 3.63944777094314 + RLHP60 * HP_ETW * -59401.3965935959 + RLHP60 * ETW * 8.04977129035753 + HP_ETW * ETW * 7.80462608067639E-02 + RLHP20 * RLHP20 * 852336.376483536 + RLHP60 * RLHP60 * 620251.888348202 + HP_ETW * HP_ETW * 2990.11761798953 + ETW * ETW * -1.29685668562444E-08)
(17.229281279127 + RLHP20 * 3281.19554853941 + RLHP60 * -1093.11929055584 + HP_ETW * -354.773649847422 + ETW * 0.100820983700518 + RLHP20 * RLHP60 * 2093639.2063385 + RLHP20 * HP_ETW * -60792.7239868145 + RLHP20 * ETW * 3.03448556782973 + RLHP60 * HP_ETW * -43345.0109706843 + RLHP60 * ETW * 4.59964822522492 + HP_ETW * ETW * -3.43748579282498E-02 + RLHP20 * RLHP20 * -2233008.51113499 + RLHP60 * RLHP60 * 193707.967212162 + HP_ETW * HP_ETW * 7894.44336508737 + ETW * ETW * 1.77071424573799E-07)
(51.9652982605103 + RLHP20 * 8112.63624490393 + RLHP60 * -29719.291811228 + HP_ETW * 670.791208277599 + ETW * 1.19964142403331E-02 + RLHP20 * RLHP60 * 1760214.52993652 + RLHP20 * HP_ETW * 48884.7464586267 + RLHP20 * ETW * -3.0468747508932 + RLHP60 * HP_ETW * -134151.498433435 + RLHP60 * ETW * 16.5196056612086 + HP_ETW * ETW * -5.00780312010795E-02 + RLHP20 * RLHP20 * -5174881.07759553 + RLHP60 * RLHP60 * 2847380.89699544 + HP_ETW * HP_ETW * 1933.97839645941 + ETW * ETW * 2.49944257702617E-08)
(9.42426552897976E-02 + RLHP20 * -8.67753548243127 + RLHP60 * -1.25433074169979 + HP_ETW * 2.36155977722839 + ETW * -5.02570130409737E-05 + RLHP20 * RLHP60 * -1346.72585688432 + RLHP20 * HP_ETW * -2.01875340702074 + RLHP20 * ETW * -2.86900770294598E-04 + RLHP60 * HP_ETW * -9.79248304114116 + RLHP60 * ETW * -8.02462001216872E-04 + HP_ETW * ETW * 1.31800222688058E-02 + RLHP20 * RLHP20 * 4522.82437754836 + RLHP60 * RLHP60 * 862.766253485694 + HP_ETW * HP_ETW * -14.9086015192973 + ETW * ETW * 4.04706726926766E-09)
(-4.82637156703734 + RLHP20 * -105.074481298302 + RLHP60 * 54.2696982370053 + HP_ETW * 151.462510854908 + ETW * 0.00130625681466241 + RLHP20 * RLHP60 * -10076.0711025307 + RLHP20 * HP_ETW * 261.577105272997 + RLHP20 * ETW * -0.010298721021474 + RLHP60 * HP_ETW * -4.07581237442843 + RLHP60 * ETW * -0.0209676757797716 + HP_ETW * ETW * -0.00296283965731266 + RLHP20 * RLHP20 * 47916.0507236993 + RLHP60 * RLHP60 * 6235.77804094256 + HP_ETW * HP_ETW * -581.199529326768 + ETW * ETW * -4.05477867514449E-08)
0
0
1
0
1
0
0
0
0
0
0
0
1
0
0
1
0
0
1
1
0
0
0
0
0
1
0
0
- Data Column Name and Description
- cost_curve_class:
Unique row identifier, specifies the powertrain package
- CHARGE-SUSTAINING SIMULATION RESULTS (example)
Column names must be consistent with the input data loaded by
class drive_cycles.DriveCycles
- cs_ftp_1:cert_direct_oncycle_co2e_grams_per_mile:
response surface equation, CO2e grams/mile
- cs_ftp_2:cert_direct_oncycle_co2e_grams_per_mile:
response surface equation, CO2e grams/mile
- cs_ftp_3:cert_direct_oncycle_co2e_grams_per_mile:
response surface equation, CO2e grams/mile
- cs_hwfet:cert_direct_oncycle_co2e_grams_per_mile:
response surface equation, CO2e grams/mile
- CHARGE-DEPLETING SIMULATION RESULTS (example)
Column names must be consistent with the input data loaded by
class drive_cycles.DriveCycles
- cd_ftp_1:cert_direct_oncycle_kwh_per_mile:
simulation result, kWh/mile
- cd_ftp_2:cert_direct_oncycle_kwh_per_mile:
simulation result, kWh/mile
- cd_ftp_3:cert_direct_oncycle_kwh_per_mile:
simulation result, kWh/mile
- cd_hwfet:cert_direct_oncycle_kwh_per_mile:
simulation result, kWh/mile
- engine_displacement_liters:
Response surface equation for engine displacement in Liters, if applicable
- engine_cylinders:
Response surface equation for number of engine cylinders, if applicable
- hev_motor_kw:
Response surface equation or scalar value for hybrid electric vehicle motor power rating in kW
- hev_batt_kwh:
Response surface equation or scalar value for hybrid electric vehicle battery capacity rating in kWh
- unibody:
= 1 if powertrain package is associated with a unibody vehicle
- high_eff_alternator:
= 1 if powertrain package qualifies for the high efficiency alternator off-cycle credit, = 0 otherwise
- start_stop:
= 1 if powertrain package qualifies for the engine start-stop off-cycle credit, = 0 otherwise
- mhev:
= 1 if powertrain package represents a mild hybrid vehicle, e.g. 48V start-stop, etc, = 0 otherwise
- hev:
= 1 if powertrain package represents a strong hybrid vehicle, e.g. a powersplit hybrid, = 0 otherwise
- hev_truck:
= 1 if powertrain package represents a hybrid truck, = 0 otherwise
- deac_pd:
= 1 if powertrain package includes partial discrete cylinder deactivation, = 0 otherwise
- deac_fc:
= 1 if powertrain package includes full continuous cylinder deactivation, = 0 otherwise
- cegr:
= 1 if powertrain package includes cooled exhaust gas recirculation, = 0 otherwise
- atk2:
= 1 if powertrain package includes an high geometric compression ratio Atkinson cycle engine, = 0 otherwise
- gdi:
= 1 if powertrain package includes a gasoline direct injection engine, = 0 otherwise
- turb12:
= 1 if powertrain package includes an advanced turbo charger, = 0 otherwise
- turb11:
= 1 if powertrain package includes a convenvtional turbo charger, = 0 otherwise
- cert_fuel_id:
= cert fuel id, e.g. ‘gasoline’
- trx10:
= 1 if powertrain package includes a baseline transmission, = 0 otherwise
- trx11:
= 1 if powertrain package includes an improved transmission, = 0 otherwise
- trx12:
= 1 if powertrain package includes an advanced transmission, = 0 otherwise
- trx21:
= 1 if powertrain package includes a high gear count transmission or equivalent, = 0 otherwise
- trx22:
= 1 if powertrain package includes an advanced high gear count transmission or equivalent, = 0 otherwise
- ecvt:
= 1 if powertrain package includes an powersplit-type hybrid vehicle transmission, = 0 otherwise
- ice:
= 1 if powertrain package is associated with an internal combustion engine, = 0 otherwise
- fcv:
= 1 if powertrain package is associated with a fuel cell vehicle, = 0 otherwise
- phev:
= 1 if powertrain package is associated with a plug-in hybrid vehicle, = 0 otherwise
- bev:
= 1 if powertrain package is associated with a battery-electric vehicle, = 0 otherwise
- drive_system:
= drive system, e.g. ‘FWD’, ‘RWD’, ‘AWD’
- application_id:
= high-load application = ‘HLA’, standard-load application = ‘SLA’, medium-duty application = ‘MDV’
CODE
- class CostCloud
Bases:
OMEGABase
,CostCloudBase
Loads and provides access to simulated vehicle data, provides methods to calculate and plot frontiers.
- cost_cloud_data_columns = {}
- cost_cloud_generated_columns = ['curbweight_lbs', 'rated_hp', 'battery_kwh', 'total_emachine_kw', 'ac_efficiency', 'ac_leakage', 'footprint_ft2', 'etw_lbs', 'cert_utility_factor', 'onroad_utility_factor', 'battery_sizing_onroad_direct_kwh_per_mile', 'tractive_motor_kw', 'cert_engine_on_distance_frac', 'onroad_engine_on_distance_frac', 'battery_mass_lbs', 'powertrain_mass_lbs', 'delta_glider_non_structure_mass_lbs', 'glider_non_structure_mass_lbs', 'structure_mass_lbs']
- cost_cloud_cost_columns = ['engine_cost', 'driveline_cost', 'emachine_cost', 'battery_cost', 'electrified_driveline_cost', 'structure_cost', 'glider_non_structure_cost']
- cloud_non_numeric_columns = ['cost_curve_class', 'structure_material', 'powertrain_type', 'vehicle_name', 'drive_system', 'application_id', 'cert_fuel_id']
- cloud_non_numeric_data_columns = ['cost_curve_class', 'structure_material', 'powertrain_type']
- tech_flags = {}
- rse_names = {}
- static init_from_ice_file(filename, powertrain_type='ICE', verbose=False)
Init
CostCloud
from ICE RSE data.- Parameters:
filename (str) – the pathname of the file to load
powertrain_type (str) – e.g. ‘ICE’
verbose (bool) – enhanced console output if
True
- Returns:
list of encountered errors, if any
- static init_from_bev_file(filename, verbose=False)
Init
CostCloud
from BEV RSE data.- Parameters:
filename (str) – the pathname of the file to load
verbose (bool) – enhanced console output if
True
- Returns:
list of encountered errors, if any
- static init_from_phev_file(filename, verbose=False)
Init
CostCloud
from PHEV RSE data.- Parameters:
filename (str) – the pathname of the file to load
verbose (bool) – enhanced console output if
True
- Returns:
list of encountered errors, if any
- static init_cost_clouds_from_files(ice_filename, bev_filename, phev_filename, verbose=False)
Initialize class data from input file.
- Parameters:
ice_filename (str) – name of ICE/HEV vehicle simulation data input file
bev_filename (str) – name of BEV vehicle simulation data input file
phev_filename (str) – name of PHEV vehicle simulation data input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
- static get_cloud(vehicle)
Retrieve cost cloud for the given vehicle.
- Parameters:
vehicle (Vehicle) – the vehicle to get the cloud for
- Returns:
Copy of the requested cost cloud data.
- static get_rse_group_key(vehicle)
Get RSE group key for the given vehicle
- Parameters:
vehicle (Vehicle) – the vehicle
- Returns:
The RSE group key
- static get_tech_flags(vehicle)
Get tech flags associated with the vehicle cost curve class
- Parameters:
vehicle (Vehicle) – the vehicle
- Returns:
Pandas Series of tech flags and values associated with the vehicle cost curve class
- static get_powertrain_type(tech_flags)
Determine powertrain type based on tech flags
- Parameters:
tech_flags (dict-like) – tech flags and values
- Returns:
Powertrain type based on tech flags
7.3.1.4. omega_model.policy package
OMEGA policy subpackage.
CODE
7.3.1.4.1. Submodules
7.3.1.4.2. omega_model.policy.credit_banking module
Routines to load initial GHG credits (in CO2e Mg), provide access to credit banking data, and handle credit transactions, along the lines of Averaging, Bank and Trading (ABT)
Not all features of ABT are implemented (notably, explicit between-manufacturer Trading). Credits can be earned, used to pay debits (model year compliance deficits) and/or may expire unused.
See also
The manufacturers
module and postproc_session.plot_manufacturer_compliance()
for credit plotting routines.
INPUT FILE FORMAT (GHG credit parameters file)
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows.
The data represents GHG credit parameters such as credit carry-forward and carry-back year limits
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
ghg_credit_params
input_template_version:
0.2
- Sample Data Columns
start_model_year
credit_carryforward_years
credit_carryback_years
2016
5
3
Data Column Name and Description
- start_model_year:
Start model year of the credit parameter
- credit_carryforward_years:
Number of years the credit can carry forward to pay future debits
- credit_carryback_years:
Number of years the credit can carry back to pay prior debits
INPUT FILE FORMAT (GHG credits file)
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows.
The data represents GHG credits that are available to manufacturers in the compliance analysis years.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
ghg_credit_history
input_template_version:
0.21
- Sample Data Columns
calendar_year
model_year
compliance_id
balance_Mg
2022
2017
consolidated_OEM
10551149
2022
2018
consolidated_OEM
21602835
Data Column Name and Description
- calendar_year:
Calendar year of the data, e.g. the analysis base year
- model_year:
The model year of the available credits, determines remaining credit life
- compliance_id:
Identifies the credit owner, consistent with the data loaded by the
manufacturers
module- balance_Mg:
Model year credit remaining balance in the calendar year (CO2e Mg)
CODE
- class CreditInfo(remaining_balance_Mg, remaining_years, model_year)
Bases:
OMEGABase
Stores GHG credit info (i.e. remaining balance, remaining years)
Used by GHG_credit_bank.get_credit_info() to return a list of non-expired credit and debit data
- __init__(remaining_balance_Mg, remaining_years, model_year)
Create GHG_credit_info object
- Parameters:
remaining_balance_Mg (numeric) – remaining credit balance, CO2e Mg
remaining_years (numeric) – remaining years of life before expiration
- class CreditBank(ghg_credit_params_filename, ghg_credits_filename, compliance_id, verbose=False)
Bases:
OMEGABase
Provides objects and methods to handle credit transactions and provide credit bank information.
Each manufacturer will use its own unique credit bank object.
- __init__(ghg_credit_params_filename, ghg_credits_filename, compliance_id, verbose=False)
Initialize credit bank data from input file, call after validating ghg_credits and ghg_params templates.
- Parameters:
ghg_credit_params_filename (str) – name of the GHG credit parameters input file
ghg_credits_filename (str | None) – name of input file containing pre-existing credit info
compliance_id (str) – name of manufacturer, e.g. ‘consolidated_OEM’
verbose (bool) – enable additional console and logfile output if True
Note
Raises exception on input file format error
See also
validate_ghg_credit_params_template()
,validate_ghg_credits_template()
- static init_ghg_credit_params(ghg_credit_params_filename, verbose)
Read GHG credit parameters input file. Call after
validate_ghg_credit_params_template()
.- Parameters:
ghg_credit_params_filename (str) – name of the GHG credit parameters input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
DataFrame of credit parameters
See also
CreditBank.validate_ghg_credit_params_template()
- static init_ghg_credit_bank(ghg_credits_filename, compliance_id, verbose)
Read GHG banked credits file and return credit bank info. Call after
validate_ghg_credits_template()
.- Parameters:
ghg_credits_filename (str) – name of input file
compliance_id (str) – manufacturer name, or ‘consolidated_OEM’
verbose (bool) – enable additional console and logfile output if True
- Returns:
DataFrame of credit bank data
See also
CreditBank.validate_ghg_credits_template()
- static validate_ghg_credit_params_template(filename, verbose)
Validate GHG credit input file template.
- Parameters:
filename (str) – name of input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template errors, or empty list on success.
- static validate_ghg_credits_template(filename, verbose)
Validate GHG credit input file template.
- Parameters:
filename (str) – name of input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template errors, or empty list on success.
- static create_credit(calendar_year, compliance_id, beginning_balance_Mg)
Create a new GHG credit data structure.
- Parameters:
calendar_year (numeric) – calendar year of credit creation
compliance_id (str) – manufacturer name, or ‘consolidated_OEM’
beginning_balance_Mg (numeric) – starting balance of credit in CO2e Mg
- Returns:
DataFrame of new (age zero) credit info
- static create_credit_transaction(credit)
Create an empty (no value, no destination) credit transaction.
- Parameters:
credit (Series) – see GHG_credit_bank.create_credit()
- Returns:
DataFrame of new, empty, credit transaction
- get_credit_param(model_year, param)
Get the given credit parameter for the given model year.
- Parameters:
model_year (int) – the model year
param (str) – the name of the paramter to retrieve
- Returns:
The given credit parameter for the given model year.
- get_credit_info(calendar_year)
Get lists of valid (non-expired) credits and debits for the given year.
- Parameters:
calendar_year (numeric) – calendar year to query for credits and debits
- Returns:
Tuple of lists of
GHG_credit_info
objects ([current_credits], [current_debits])
- get_expiring_credits_Mg(calendar_year)
Get value of expiring credits in CO2e Mg for the given year.
- Parameters:
calendar_year (numeric) – calendar year to get expiring credits from
- Returns:
Value of expiring credits in CO2e Mg
- get_expiring_debits_Mg(calendar_year)
Get value of expiring debits in CO2e Mg for the given year.
- Parameters:
calendar_year (numeric) – calendar year to get expiring debits from
- Returns:
Value of expiring debits in CO2e Mg
- update_credit_age(calendar_year)
Take each credit in the
credit_bank
and age it by one year then apply lifetime limits to drop expired credits and zero-value credits and debits.Credits and debits with zero balance are dropped silently after age zero.
Expiration takes the form of entries in the
transaction_log
.Expiring credits with non-zero balances are marked as ‘EXPIRATION’ transactions and then dropped
Expiring debits with non-zero balances are marked as ‘PAST_DUE’ transactions and are then dropped
Result is an updated
credit_bank
and an updatedtransaction_log
, as needed- Parameters:
calendar_year (numeric) – calendar year to update credits in
- handle_credit(calendar_year, beginning_balance_Mg)
Handle mandatory credit (and default debit) behavior.
If the manufacturer’s compliance state in the given year is over-compliance,
beginning_balance_Mg
will be positive (> 0). In this case past under-compliance (debits) MUST be paid before banking any excess. Debits are paid starting with the oldest first and working forwards until they are all paid or the full value of the current credit has been paid out, whichever comes first.If the manufacturer’s compliance state in the given year is under-compliance,
beginning_balance_Mg
will be negative (< 0). In this case, the payment of debits is up to the programmer, there are no mandatory debit payment requirements. As implemented, fresh debits are immediately paid by any available banked credits, so a debit will only be carried if it can’t be paid in full at the time of its creation.Result is an updated
credit_bank
and an updatedtransaction_log
, as needed (via thepay_debit()
method).Note
It’s possible to conceive of many different credit/debit strategies (once mandatory credit behavior has been handled). In the case of OMEGA, strategic over- and under-compliance will eventually be handled by the year-over-year compliance tree which will allow a search of various “earn and burn” credit paths. As such, it’s important to leave the implimentation of such schemes out of this method and the default handling here allows for that.
- Parameters:
calendar_year (numeric) – calendar year of credit creation
beginning_balance_Mg (numeric) – starting balance of credit (or debit) in CO2e Mg
- pay_debit(credit, debit, this_years_credits)
Pay a debit with a credit, create a transaction in the
transaction_log
and update manufacter model year compliance status (in CO2e Mg).Other than expiration, paying debits is the only way credits can be consumed.
Result is an updated
transaction_log
andManufacturerAnnualData
for the model years involved in the transaction.See also
manufacturer_annual_data.ManufacturerAnnualData.update_model_year_cert_co2e_Mg()
- Parameters:
credit (Series) – source credit to pay from
debit (Series) – destination debit to pay
this_years_credits (DataFrame) – DataFrame containing the valid, non-expired credits and debits in the current year.
7.3.1.4.3. omega_model.policy.drive_cycle_ballast module
Drive cycle ballast module.
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows.
The data represents the additional weight present during certification drive cycle testing, in pounds.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
drive_cycle_ballast
input_template_version:
0.1
notes:
20230104
- Sample Data Columns
start_year
reg_class_id
ballast_lbs
1974
car
300
1974
truck
300
1974
mediumduty
(vehicle.gvwr_lbs + vehicle.curbweight_lbs)/2
Data Column Name and Description
- start_year:
Start year of parameters, parameters apply until the next available start year
- reg_class_id:
Name of the regulatory class, e.g. ‘car’, ‘truck’, etc
- ballast_lbs:
The drive cycle test weight ballast in pounds, scalar value or expression to be evaluated
CODE
- class DriveCycleBallast
Bases:
OMEGABase
Loads and provides access to drive cycle ballast data.
- static get_ballast_lbs(vehicle)
Get drive cycle ballast for the given vehicle.
- Parameters:
vehicle (Vehicle) – the vehicle to get drive cycle ballast for
- Returns:
Drive cycle ballast in pounds
- static init_from_file(filename, verbose=False)
Initialize class data from input file.
- Parameters:
filename (str) – name of input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
7.3.1.4.4. omega_model.policy.drive_cycle_weights module
Routines to load cycle weight values and perform tree-based drive cycle weighting (distance-share based)
For vehicle certification purposes, vehicles are tested by driving several drive cycles and drive cycle phases. The phases and cycles are weighted (by distance shares) and combined to arrive at a certification on-cycle test result. One way to represent the cycle weightings is the use of a tree, where the leaves are the drive cycle or phase results, the nodes store the weight factors and the edges represent the relationships of phases to tests and the tests to each other.
class DriveCycleWeights
loads the share tree input file, validates the leaves of the tree against known cycles
and provides methods to query the tree for weighted results. Most of the heavy lifting is done by
class WeightedTree
, see omega_trees.py
Child share weights must add up to 1.0 at each node of the tree, with the exception of weights with the value None
,
these are used to ignore unused nodes (different vehicle types have different numbers of drive cycle phases but share
the same overall tree).
Drive cycles and weights may vary model year, depending on the policy being simulated, the share tree supports this.
- Sample Drive Cycle Weight Tree
1.0[weighted_combined] ├── 1[cd_cert_direct_oncycle_kwh_per_mile] │ ├── 0.55[cd_ftp_kwh] │ │ ├── 0.20726577181208053[cd_ftp_1:cert_direct_oncycle_kwh_per_mile] │ │ ├── 0.517986577181208[cd_ftp_2:cert_direct_oncycle_kwh_per_mile] │ │ ├── 0.2747476510067114[cd_ftp_3:cert_direct_oncycle_kwh_per_mile] │ │ └── None[cd_ftp_4:cert_direct_oncycle_kwh_per_mile] │ └── 0.45[cd_hwfet:cert_direct_oncycle_kwh_per_mile] └── 0[cs_cert_direct_oncycle_co2e_grams_per_mile] ├── 0.55[cs_ftp_co2] │ ├── 0.20726577181208053[cs_ftp_1:cert_direct_oncycle_co2e_grams_per_mile] │ ├── 0.517986577181208[cs_ftp_2:cert_direct_oncycle_co2e_grams_per_mile] │ ├── 0.2747476510067114[cs_ftp_3:cert_direct_oncycle_co2e_grams_per_mile] │ └── None[cs_ftp_4:cert_direct_oncycle_co2e_grams_per_mile] └── 0.45[cs_hwfet:cert_direct_oncycle_co2e_grams_per_mile]
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows. The data header uses a dynamic column notation, as detailed below.
The data represents drive-cycle weighting factors (distance shares) in a hierarchical tree datastructure, by model year
and fueling class. For details on how the header is parsed into a tree, see common.omega_trees.WeightedTree
.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
share_tree
input_template_version:
0.3
- Sample Data Columns
start_year
share_id
fueling_class
root->cs_cert_direct_oncycle_co2e_grams_per_mile
root->cd_cert_direct_oncycle_co2e_grams_per_mile
root->cs_cert_direct_oncycle_kwh_per_mile
root->cd_cert_direct_oncycle_kwh_per_mile
root->cd_engine_on_distance_frac
root->cs_engine_on_distance_frac
cd_cert_direct_oncycle_kwh_per_mile->cd_ftp_kwh
cd_cert_direct_oncycle_kwh_per_mile->cd_hwfet:cert_direct_oncycle_kwh_per_mile
cd_cert_direct_oncycle_kwh_per_mile->cd_us06_1:cert_direct_oncycle_kwh_per_mile
cd_cert_direct_oncycle_kwh_per_mile->cd_us06_2:cert_direct_oncycle_kwh_per_mile
cd_ftp_kwh->cd_ftp_1:cert_direct_oncycle_kwh_per_mile
cd_ftp_kwh->cd_ftp_2:cert_direct_oncycle_kwh_per_mile
cd_ftp_kwh->cd_ftp_3:cert_direct_oncycle_kwh_per_mile
cd_ftp_kwh->cd_ftp_4:cert_direct_oncycle_kwh_per_mile
cd_cert_direct_oncycle_co2e_grams_per_mile->cd_ftp_co2
cd_cert_direct_oncycle_co2e_grams_per_mile->cd_hwfet:cert_direct_oncycle_co2e_grams_per_mile
cd_cert_direct_oncycle_co2e_grams_per_mile->cd_us06_1:cert_direct_oncycle_co2e_grams_per_mile
cd_cert_direct_oncycle_co2e_grams_per_mile->cd_us06_2:cert_direct_oncycle_co2e_grams_per_mile
cd_ftp_co2->cd_ftp_1:cert_direct_oncycle_co2e_grams_per_mile
cd_ftp_co2->cd_ftp_2:cert_direct_oncycle_co2e_grams_per_mile
cd_ftp_co2->cd_ftp_3:cert_direct_oncycle_co2e_grams_per_mile
cd_ftp_co2->cd_ftp_4:cert_direct_oncycle_co2e_grams_per_mile
cs_cert_direct_oncycle_kwh_per_mile->cs_ftp_kwh
cs_cert_direct_oncycle_kwh_per_mile->cs_hwfet:cert_direct_oncycle_kwh_per_mile
cs_cert_direct_oncycle_kwh_per_mile->cs_us06_1:cert_direct_oncycle_kwh_per_mile
cs_cert_direct_oncycle_kwh_per_mile->cs_us06_2:cert_direct_oncycle_kwh_per_mile
cs_ftp_kwh->cs_ftp_1:cert_direct_oncycle_kwh_per_mile
cs_ftp_kwh->cs_ftp_2:cert_direct_oncycle_kwh_per_mile
cs_ftp_kwh->cs_ftp_3:cert_direct_oncycle_kwh_per_mile
cs_ftp_kwh->cs_ftp_4:cert_direct_oncycle_kwh_per_mile
cs_cert_direct_oncycle_co2e_grams_per_mile->cs_ftp_co2
cs_cert_direct_oncycle_co2e_grams_per_mile->cs_hwfet:cert_direct_oncycle_co2e_grams_per_mile
cs_cert_direct_oncycle_co2e_grams_per_mile->cs_us06_1:cert_direct_oncycle_co2e_grams_per_mile
cs_cert_direct_oncycle_co2e_grams_per_mile->cs_us06_2:cert_direct_oncycle_co2e_grams_per_mile
cs_ftp_co2->cs_ftp_1:cert_direct_oncycle_co2e_grams_per_mile
cs_ftp_co2->cs_ftp_2:cert_direct_oncycle_co2e_grams_per_mile
cs_ftp_co2->cs_ftp_3:cert_direct_oncycle_co2e_grams_per_mile
cs_ftp_co2->cs_ftp_4:cert_direct_oncycle_co2e_grams_per_mile
cd_engine_on_distance_frac->cd_ftp_engine_on_distance_frac
cd_engine_on_distance_frac->cd_hwfet:engine_on_distance_frac
cd_engine_on_distance_frac->cd_us06_1:engine_on_distance_frac
cd_engine_on_distance_frac->cd_us06_2:engine_on_distance_frac
cd_ftp_engine_on_distance_frac->cd_ftp_1:engine_on_distance_frac
cd_ftp_engine_on_distance_frac->cd_ftp_2:engine_on_distance_frac
cd_ftp_engine_on_distance_frac->cd_ftp_3:engine_on_distance_frac
cd_ftp_engine_on_distance_frac->cd_ftp_4:engine_on_distance_frac
cs_engine_on_distance_frac->cs_ftp_engine_on_distance_frac
cs_engine_on_distance_frac->cs_hwfet:engine_on_distance_frac
cs_engine_on_distance_frac->cs_us06_1:engine_on_distance_frac
cs_engine_on_distance_frac->cs_us06_2:engine_on_distance_frac
cs_ftp_engine_on_distance_frac->cs_ftp_1:engine_on_distance_frac
cs_ftp_engine_on_distance_frac->cs_ftp_2:engine_on_distance_frac
cs_ftp_engine_on_distance_frac->cs_ftp_3:engine_on_distance_frac
cs_ftp_engine_on_distance_frac->cs_ftp_4:engine_on_distance_frac
0
onroad
ICE
None
None
None
None
None
None
None
None
None
None
None
None
None
None
None
None
None
None
None
None
None
None
0.27
0
0.06
0.67
None
None
None
None
0.27
0
0.06
0.67
0.43*3.591/7.45
3.859/7.45
0.57*3.591/7.45
None
None
None
None
None
None
None
None
None
0.27
0
0.06
0.67
0.43*3.591/7.45
3.859/7.45
0.57*3.591/7.45
None
- Data Column Name and Description
- start_year:
The earliest model year that drive cycle weighting applies to
- share_id:
The type of the drive cycle weighting, e.g. ‘onroad’, ‘cert’, etc
- fueling_class:
The fueling class (general powertrain type) that the drive cycle weighting applies to, e.g. ‘ICE’, ‘PHEV’, etc
CODE
- class DriveCycleWeights
Bases:
OMEGABase
Loads a drive cycle share tree, validates cycle/phase names and provides methods to calculate weighted drive cycle results.
- static validate_drive_cycle_names(tree, filename)
Validate share tree input file leaf names against known drive cycles and phases.
- Parameters:
tree (class WeightedTree) – share tree with drive cycles/phases as leaves
filename (str) – name of input file being validated, for error messages
- Returns:
List of cycle name errors, or empty list on success.
- static init_from_file(filename, verbose=False)
Initialize class data from input file. Validate drive cycle names and share weight sums.
- Parameters:
filename (str) – name of input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
- static calc_weighted_value(calendar_year, fueling_class, cycle_values, node_id=None, weighted=True)
Query the share tree for a value or weighted value. A node’s value is either a raw cycle result (for leaves) or the sum of the weighted values of its children. A node’s weighted value is it’s value times its weight.
- Parameters:
calendar_year (numeric) – calendar year to calculated weighted value in
fueling_class (str) – e.g. ‘ICE’, ‘BEV’, etc
cycle_values (DataFrame) – contains cycle values to be weighted (e.g. the simulated vehicles input data with results (columns) for each drive cycle phase)
node_id (str) – name of tree node at which to calculated weighted value, e.g. ‘cs_cert_direct_oncycle_co2e_grams_per_mile’
weighted (bool) – if True, return weighted value at node (node value * weight), else return node value (e.g. cycle result)
- Returns:
A pandas
Series
object of the weighted results
- static calc_cert_direct_oncycle_co2e_grams_per_mile(calendar_year, fueling_class, cycle_values)
Calculate cert direct on-cycle CO2e g/mi
- Parameters:
calendar_year (numeric) – calendar year to calculated weighted value in
fueling_class (str) – e.g. ‘ICE’, ‘BEV’, etc
cycle_values (DataFrame) – contains cycle values to be weighted (e.g. the simulated vehicles input data with results (columns) for each drive cycle phase)
- Returns:
A pandas
Series
object of the weighted results
- static calc_cert_direct_oncycle_kwh_per_mile(calendar_year, fueling_class, cycle_values, charge_depleting_only=False)
Calculate cert direct on-cycle kWh/mi
- Parameters:
calendar_year (numeric) – calendar year to calculated weighted value in
fueling_class (str) – e.g. ‘ICE’, ‘BEV’, etc
cycle_values (DataFrame) – contains cycle values to be weighted (e.g. the simulated vehicles input data with results (columns) for each drive cycle phase)
charge_depleting_only (Boolean) –
True
if calculating charge-depleting kWh/mi, not cert
- Returns:
A pandas
Series
object of the weighted results
- static calc_engine_on_distance_frac(calendar_year, fueling_class, cycle_values, utility_factor=1)
Calculate engine-on distance frac
- Parameters:
calendar_year (numeric) – calendar year to calculated weighted value in
fueling_class (str) – e.g. ‘ICE’, ‘BEV’, etc
cycle_values (DataFrame) – contains cycle values to be weighted (e.g. the simulated vehicles input data with results (columns) for each drive cycle phase)
utility_factor (float) – the utility factor for PHEVs
- Returns:
The engine-on distance frac
- static calc_phev_utility_factors(calendar_year, cycle_values)
Calculate PHEV utility factors
- Parameters:
calendar_year (numeric) – calendar year to utility factors in
cycle_values (dict) – holds charge-depleting and charge-sustaining cycle phase values
- Returns:
tuple (FTP, HWFET, US06) utility factors
7.3.1.4.5. omega_model.policy.drive_cycles module
Routines to load, validate, and provide access to drive cycle definition data
Drive cycles and cycle phases are defined by a name, a distance and a brief description.
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows.
The data represents drive cycles by name/phase, a distance and a brief description.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
drive_cycles
input_template_version:
0.2
- Sample Data Columns
drive_cycle_id
drive_cycle_distance_miles
description
cs_ftp_1:cert_direct_oncycle_co2e_grams_per_mile
3.591
Charge Sustaining EPA UDDS cycle phase 1 CO2e g/mi
cs_hwfet:cert_direct_oncycle_co2e_grams_per_mile
10.26
Charge Sustaining EPA HWFET cycle CO2e g/mi
Data Column Name and Description
- drive_cycle_id:
Name of the drive cycle or drive cycle phase. This must be consistent the leaves of the drive cycle weights tree, see also
drive_cycle_weights.DriveCycleWeights
.- drive_cycle_distance_miles:
Drive cycle/phase distances (miles).
- description:
A brief description of the drive cycle/phase.
CODE
- class DriveCycles
Bases:
OMEGABase
Load and provides routines to access drive cycle descriptive data
- drive_cycle_names = []
list of available drive cycles (may not all be used, depends on the simulated vehicles data)
- static validate_drive_cycle_id(drive_cycle_id)
Validate drive cycle name.
- Parameters:
drive_cycle_id (str) – drive cycle name to validate e.g. ‘cs_hwfet:cert_direct_oncycle_co2e_grams_per_mile’
- Returns:
True if drive cycle name is in the list of known drive cycles.
- static get_drive_cycle_distance_miles(drive_cycle_id)
Get the target driven distance (in miles) of a drive cycle
- Parameters:
drive_cycle_id (str) – drive cycle name
- Returns:
Drive cycle distance in miles
- static init_from_file(filename, verbose=False)
Initialize class data from input file.
- Parameters:
filename (str) – name of input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
7.3.1.4.6. omega_model.policy.incentives module
Routines to load and provide access to ‘incentives’ such as production multipliers for battery-electric vehicles.
Currently, only production multipliers are implemented here, but other incentives may be added later.
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows. The data header uses a dynamic column notation, as detailed below.
The data represents production multiplier incentives as a function of vehicle attribute values.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
production_multipliers
input_template_version:
0.21
description:
20230208 2021 final rulemaking production_multipliers
- Sample Data Columns
start_year
fueling_class:BEV
2020
2.0
- Data Column Name and Description
- start_year:
Start year of incentive, incentive applies until the next available start year
- dynamic column(s):
Zero or more dynamic columns with the format
{attribute_name}:{attribute_value}
Unspecified vehicle attribute-value pairs will have a production multiplier of 1.0, so only non-1.0 multipliers need to be specified here.
- Example:
fueling_class:BEV
=>if vehicle.fueling_class == 'BEV' then apply production multiplier
CODE
- class Incentives
Bases:
OMEGABase
Loads and provides access to GHG incentives.
- static get_production_multiplier(vehicle)
Get production multiplier (if any) for the given vehicle.
- Parameters:
vehicle (Vehicle) – the vehicle to get the multiplier for
- Returns:
The production multiplier, if applicable, or 1.0
- static init_from_file(filename, verbose=False)
Initialize class data from input file.
- Parameters:
filename (str) – name of input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
7.3.1.4.7. omega_model.policy.offcycle_credits module
Routines to load, access and apply off-cycle credit values
Off-cycle credits represent GHG benefits of technologies that have no or limited on-cycle benefits.
For example, LED headlights have a real-world (“off-cycle”) benefit but are not represented during certification testing (tests are performed with headlights off).
As another example, engine Stop-Start has an on-cycle benefit but the vehicle idle duration during testing may under-represent vehicle idle duration in real-world driving so there may be some additional benefit available.
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows. The template header uses a dynamic format. The data header uses a dynamic column notation, as detailed below.
The data represents offcycle credit values (grams CO2e/mile) credit group and regulatory class.
- File Type
comma-separated values (CSV)
- Template Header
input_template_name:
[module_name]
input_template_version:
[template_version]
- Sample Header
input_template_name:
policy.offcycle_credits
input_template_version:
0.11
description:
20231106
The data header consists of start_year
, credit_name
, credit_group
, credit_destination
columns
followed by zero or more reg class columns, as needed.
- Dynamic Data Header
start_year
credit_name
credit_group
credit_destination
reg_class_id:{reg_class_id}
…
- Sample Data Columns
start_year
credit_name
credit_group
credit_destination
fueling_class_reg_class_id:ICE.car
fueling_class_reg_class_id:ICE.truck
fueling_class_reg_class_id:BEV.car
fueling_class_reg_class_id:BEV.truck
fueling_class_reg_class_id:PHEV.car
fueling_class_reg_class_id:PHEV.truck
2020
start_stop
menu
cert_direct_offcycle_co2e_grams_per_mile
2.5
4.4
0
0
2.5
4.4
2020
other_oc_menu_tech
menu
cert_direct_offcycle_co2e_grams_per_mile
7.5
5.6
5.3
7
7.5
5.6
2020
ac_leakage
ac
cert_indirect_offcycle_co2e_grams_per_mile
13.8
17.2
13.8
17.2
13.8
17.2
2020
ac_efficiency
ac
cert_direct_offcycle_co2e_grams_per_mile
5
7.2
5
7.2
5
7.2
Data Column Name and Description
- start_year:
Start year of production constraint, constraint applies until the next available start year
- credit_name:
Name of the offcycle credit
- credit_group:
Group name of the offcycle credit, in case of limits within a group of credits (work in progress)
- credit_destination:
Name of the vehicle CO2e attribute to apply the credit to, e.g.
cert_direct_offcycle_co2e_grams_per_mile
,cert_indirect_offcycle_co2e_grams_per_mile
Optional Columns
fueling_class_reg_class_id:{fueling_class_reg_class_id}
:The value of the credits. Credits are specified as positive numbers and are subtracted from the cert results to determine a compliance result
CODE
- class OffCycleCredits
Bases:
OMEGABase
,OffCycleCreditsBase
Loads, stores and applies off-cycle credits to vehicle cost clouds
- offcycle_credit_names = []
list of credit names, populated during init, used to track credits across composition/decomposition, also used to check simulated vehicles for necessary columns
- static calc_off_cycle_credits(calendar_year, vehicle, cost_cloud)
Calculate vehicle off-cycle credits for the vehicle’s cost cloud
- Parameters:
calendar_year (int) – the year to calculate credits for, usually the vehicle model year
vehicle (Vehicle) – the vehicle to apply off-cycle credits to
cost_cloud (DataFrame) – destination data set for off-cycle credits
- Returns:
cost_cloud with off-cycle credits calculated
- static init_from_file(filename, verbose=False)
Initialize class data from input file.
- Parameters:
filename – name of input file
verbose – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
7.3.1.4.8. omega_model.policy.policy_base_classes module
A set of base classes used to define the program interface(s) and to serve as templates for user-defined classes
Ordinarily these classes might be implemented as Python abstract classes but abstract classes cause issues when combined with SQLAlchemy base classes, so the implementation here is a workaround - if a child class fails to implement one of the required methods, the class will throw a runtime Exception or return an error message.
- class RegulatoryClassesBase
Bases:
object
Load and provides routines to access to regulatory class descriptive data
- static get_vehicle_reg_class(vehicle)
Get vehicle regulatory class based on vehicle characteristics.
- Parameters:
vehicle (Vehicle) – the vehicle to determine the reg class of
- Returns:
Vehicle reg class based on vehicle characteristics.
- static init_from_file(filename, verbose=False)
Initialize class data from input file.
- Parameters:
filename (str) – name of input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
- class VehicleTargetsBase
Bases:
object
A base class representing the program interface for calculating vehicle CO g/mi targets.
- static calc_target_co2e_gpmi(vehicle)
Calculate vehicle target CO2e g/mi.
- Parameters:
vehicle (Vehicle) – the vehicle to get the target for
- Returns:
Vehicle target CO2e in g/mi.
- static calc_cert_lifetime_vmt(reg_class_id, model_year)
Get lifetime VMT as a function of regulatory class and model year.
- Parameters:
reg_class_id (str) – e.g. ‘car’,’truck’
model_year (numeric) – model year
- Returns:
Lifetime VMT for the regulatory class and model year.
- static calc_cert_useful_life_vmt(reg_class_id, model_year, cert_fuel_id)
Get lifetime VMT as a function of regulatory class and model year.
- Parameters:
reg_class_id (str) – e.g. ‘car’,’truck’
model_year (numeric) – model year
cert_fuel_id (str) – certification fuel id, e.g. ‘gasoline’
- Returns:
Lifetime VMT for the regulatory class and model year.
- static calc_target_co2e_Mg(vehicle, sales_variants=None)
Calculate vehicle target CO2e Mg as a function of the vehicle, the standards and optional sales options.
Includes the effect of production multipliers.
See also
GHG_standards_incentives.GHGStandardIncentives
- Parameters:
vehicle (Vehicle) – the vehicle
sales_variants (numeric list-like) – optional sales variants
- Returns:
Target CO2e Mg value(s) for the given vehicle and/or sales variants.
- static calc_cert_co2e_Mg(vehicle, co2_gpmi_variants=None, sales_variants=1)
Calculate vehicle cert CO2e Mg as a function of the vehicle, the standards, CO2e g/mi options and optional sales options.
Includes the effect of production multipliers.
See also
GHG_standards_incentives.GHGStandardIncentives
- Parameters:
vehicle (Vehicle) – the vehicle
co2_gpmi_variants (numeric list-like) – optional co2 g/mi variants
sales_variants (numeric list-like) – optional sales variants
- Returns:
Cert CO2e Mg value(s) for the given vehicle, CO2e g/mi variants and/or sales variants.
- static init_from_file(filename, verbose=False)
Initialize class data from input file.
- Parameters:
filename (str) – name of input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
- class OffCycleCreditsBase
Bases:
object
Loads, stores and applies off-cycle credits to vehicle cost clouds
- offcycle_credit_names = []
list of credit names, populated during init, used to track credits across composition/decomposition, also used to check simulated vehicles for necessary columns
- static calc_off_cycle_credits(calendar_year, vehicle, cost_cloud)
Calculate vehicle off-cycle credits for the vehicle’s cost cloud
- Parameters:
calendar_year (int) – the year to calculate credits for, usually the vehicle model year
vehicle (Vehicle) – the vehicle to apply off-cycle credits to
cost_cloud (DataFrame) – destination data set for off-cycle credits
- Returns:
cost_cloud with off-cycle credits calculated
- static init_from_file(filename, verbose=False)
Initialize class data from input file.
- Parameters:
filename (str) – name of input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
7.3.1.4.9. omega_model.policy.policy_fuels module
Routines to load and provide access to policy-defined fuel attributes.
The primary fuel attributes are CO2e grams per unit (i.e. g/gallon, g/kWh) when consumed, by policy year.
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows.
The data represents fuel property data for compliance purposes, by policy year.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
policy-fuels
input_template_version:
0.1
- Sample Data Columns
fuel_id
start_year
unit
direct_co2e_grams_per_unit
upstream_co2e_grams_per_unit
transmission_efficiency
electricity
2020
kWh
0
534
0.935
gasoline
2020
gallon
8887
2478
0
diesel
2020
gallon
10180
2839
0
Data Column Name and Description
- fuel_id:
The Fuel ID, as referenced by the
policy_fuel_upstream
module.- start_year:
Start year of fuel properties, properties apply until the next available start year
- unit:
Fuel unit, e.g. ‘gallon’, ‘kWh’
- direct_co2e_grams_per_unit:
CO2e emissions per unit when consumed
- upstream_co2e_grams_per_unit:
Upstream CO2e emissions per unit when consumed
- transmission_efficiency:
Fuel transmission efficiency [0..1], e.g. electrical grid efficiency, may also be referred to as “grid loss”
CODE
- class PolicyFuel
Bases:
OMEGABase
Loads and provides methods to access onroad fuel attribute data.
- fuel_ids = []
- static get_fuel_attribute(calendar_year, fuel_id, attribute)
- Parameters:
calendar_year (numeric) – year to get fuel properties in
fuel_id (str) – e.g. ‘pump gasoline’)
attribute (str) – name of attribute to retrieve
- Returns:
Fuel attribute value for the given year.
Example
carbon_intensity_gasoline = PolicyFuel.get_fuel_attribute(2020, 'pump gasoline', 'direct_co2e_grams_per_unit')
- static init_from_file(filename, verbose=False)
Initialize class data from input file.
- Parameters:
filename (str) – name of input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
7.3.1.4.10. omega_model.policy.regulatory_classes module
Routines to load, validate, and provide access to regulatory class (“reg” class) definition data
Reg classes are defined by a name, and a brief description.
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows. The template header uses a dynamic format.
The data represents regulatory classes by name and a brief description.
- File Type
comma-separated values (CSV)
- Template Header
input_template_name:
[module_name]
input_template_version:
[template_version]
[other]
- Sample Header
input_template_name:
policy.regulatory_classes
input_template_version:
0.1
notes:
20221019 Added mediumduty reg class
- Sample Data Columns
reg_class_id
description
car
cars as defined by the regulations
truck
trucks as defined by the regulations
mediumduty
medium duty as defined by the regulations
Data Column Name and Description
- reg_class_id:
Name of the regulatory class.
- description:
A brief description of the regulatory class.
CODE
- class RegulatoryClasses
Bases:
OMEGABase
,RegulatoryClassesBase
Load and provides routines to access to regulatory class descriptive data
- reg_classes = None
- static get_vehicle_reg_class(vehicle)
Get vehicle regulatory class based on vehicle characteristics.
- Parameters:
vehicle (Vehicle) – the vehicle to determine the reg class of
- Returns:
Vehicle reg class based on vehicle characteristics.
- static init_from_file(filename, verbose=False)
Initialize class data from input file.
- Parameters:
filename (str) – name of input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
7.3.1.4.12. omega_model.policy.targets_footprint module
Loads parameters and provides calculations for an attribute-based (vehicle footprint) GHG standard.
This is based on the current standards, with two regulatory classes with lifetime VMT and parameter-based target calculations that define a “footprint curve” based on four coefficients (“A” through “D”) and min and max footprint limits.
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows. The template header uses a dynamic format.
The data represents a set of GHG standards (vehicle target CO2e g/mi) by regulatory class and model year as a function of vehicle footprint in square feet.
- File Type
comma-separated values (CSV)
- Template Header
input_template_name:
[module_name]
input_template_version:
[template_version]
[other]
- Sample Header
input_template_name:
policy.targets_footprint
input_template_version:
0.11
Notes:
20230208_yoy_b_to2032_C_b50_74_m0p35_T_b50_83_m1p38
- Sample Data Columns
reg_class_id
start_year
fp_min
fp_max
a_coeff
b_coeff
c_coeff
d_coeff
lifetime_vmt
car
2020
41
56
166
226
4.01
1.9
195264
truck
2020
41
68.3
212
337
4.57
24.6
225865
Data Column Name and Description
- reg_class_id:
Regulatory class name, e.g. ‘car’, ‘truck’
- start_year:
The start year of the standard coefficients, applies until the next available start year
- fp_min:
Minimum footprint limit of the curve (square feet)
- fp_max:
Maximum footprint limit of the curve (square feet)
- a_coeff:
Footprint curve “A” coefficient
- b_coeff:
Footprint curve “B” coefficient
- c_coeff:
Footprint curve “C” coefficient
- d_coeff:
Footprint curve “D” coefficient
- lifetime_vmt:
Lifetime Vehicle Miles Travelled for computing CO2e Mg
CODE
- class VehicleTargets
Bases:
OMEGABase
,VehicleTargetsBase
Implements vehicle footprint-based GHG targets (CO2e g/mi).
- static calc_target_co2e_gpmi(vehicle)
Calculate vehicle target CO2e g/mi.
- Parameters:
vehicle (Vehicle) – the vehicle to get the target for
- Returns:
Vehicle target CO2e in g/mi.
- static calc_cert_lifetime_vmt(reg_class_id, model_year)
Get lifetime VMT as a function of regulatory class and model year.
- Parameters:
reg_class_id (str) – e.g. ‘car’,’truck’
model_year (numeric) – model year
- Returns:
Lifetime VMT for the regulatory class and model year.
- static calc_target_co2e_Mg(vehicle, sales_variants=None)
Calculate vehicle target CO2e Mg as a function of the vehicle, the standards and optional sales options.
Includes the effect of production multipliers.
See also
GHG_standards_incentives.GHGStandardIncentives
- Parameters:
vehicle (Vehicle) – the vehicle
sales_variants (numeric list-like) – optional sales variants
- Returns:
Target CO2e Mg value(s) for the given vehicle and/or sales variants.
- static calc_cert_co2e_Mg(vehicle, co2_gpmi_variants=None, sales_variants=1)
Calculate vehicle cert CO2e Mg as a function of the vehicle, the standards, CO2e g/mi options and optional sales options.
Includes the effect of production multipliers.
See also
GHG_standards_incentives.GHGStandardIncentives
- Parameters:
vehicle (Vehicle) – the vehicle
co2_gpmi_variants (numeric list-like) – optional co2 g/mi variants
sales_variants (numeric list-like) – optional sales variants
- Returns:
Cert CO2e Mg value(s) for the given vehicle, CO2e g/mi variants and/or sales variants.
- static init_from_file(filename, verbose=False)
Initialize class data from input file.
- Parameters:
filename (str) – name of input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
7.3.1.4.13. omega_model.policy.targets_workfactor module
Loads parameters and provides calculations for an attribute-based (vehicle work factor) GHG standard.
This is based on the current work factor based standards, with two liquid fuel types and with lifetime VMT and parameter-based target calculations based on work factor with work factor defined in the work_factor_definition file.
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows. The template header uses a dynamic format.
The data represent a set of GHG standards (vehicle target CO2e g/mi) by fuel type and model year as a function of work factor.
- File Type
comma-separated values (CSV)
- Template Header
input_template_name:
[module_name]
input_template_version:
[template_version]
- Sample Header
input_template_name:
policy.targets_workfactor
input_template_version:
0.1
- Sample Data Columns
reg_class_id
start_year
cert_fuel_id
useful_life_miles
co2_gram_per_mile
mediumduty
2020
{‘gasoline’:1.0}
120000
0.0440 * workfactor + 339
mediumduty
2021
{‘gasoline’:1.0}
120000
0.0429 * workfactor + 331
mediumduty
2022
{‘gasoline’:1.0}
120000
0.0418 * workfactor + 322
Data Column Name and Description
- reg_class_id:
Regulatory class name, e.g. ‘mediumduty’
- start_year:
The start year of the standard, applies until the next available start year
- cert_fuel_id:
Minimum footprint limit of the curve (square feet)
- useful_life_miles:
The regulatory useful life during which the standard applies and used for computing CO2e Mg
- co2_gram_per_mile:
The co2 gram per mile standard.
CODE
- class VehicleTargets
Bases:
OMEGABase
,VehicleTargetsBase
Implements vehicle workfactor-based GHG targets (CO2e g/mi).
- start_years = {}
- static calc_target_co2e_gpmi(vehicle)
Calculate vehicle target CO2e g/mi.
- Parameters:
vehicle (Vehicle) – the vehicle to get the target for
- Returns:
Vehicle target CO2e in g/mi.
- static calc_cert_useful_life_vmt(reg_class_id, model_year, cert_fuel_id)
Calculate the certification useful life vehicle miles travelled.
- Parameters:
reg_class_id (str) – e.g. ‘car’, ‘truck’
model_year (int) – the model year to get useful life VMT for
cert_fuel_id (str) – certification fuel id, e.g. ‘gasoline’
- Returns:
The certification useful life vehicle miles travelled.
- static calc_target_co2e_Mg(vehicle, sales_variants=None)
Calculate vehicle target CO2e Mg as a function of the vehicle, the standards and optional sales options.
Includes the effect of production multipliers.
See also
GHG_standards_incentives.GHGStandardIncentives
- Parameters:
vehicle (Vehicle) – the vehicle
sales_variants (numeric list-like) – optional sales variants
- Returns:
Target CO2e Mg value(s) for the given vehicle and/or sales variants.
- static calc_cert_co2e_Mg(vehicle, co2_gpmi_variants=None, sales_variants=1)
Calculate vehicle cert CO2e Mg as a function of the vehicle, the standards, CO2e g/mi options and optional sales options.
Includes the effect of production multipliers.
See also
GHG_standards_incentives.GHGStandardIncentives
- Parameters:
vehicle (Vehicle) – the vehicle
co2_gpmi_variants (numeric list-like) – optional co2 g/mi variants
sales_variants (numeric list-like) – optional sales variants
- Returns:
Cert CO2e Mg value(s) for the given vehicle, CO2e g/mi variants and/or sales variants.
- static init_from_file(filename, verbose=False)
Initialize class data from input file.
- Parameters:
filename (str) – name of input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
7.3.1.4.14. omega_model.policy.upstream_methods module
Routines to load and apply upstream calculation methods.
Upstream calculation methods calculate cert CO2e g/mi from kWh/mi.
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows.
The data represents the calculation method(s) to apply by start year.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
policy_fuel_upstream_methods
input_template_version:
0.2
- Sample Data Columns
start_year
upstream_calculation_method
2020
upstream_xev_ice_delta
2025
upstream_actual
Data Column Name and Description
- start_year:
Start year of the upstream calculation method, method applies until the next available start year
- upstream_calculation_method:
The name of the function to call within
upstream_methods.py
CODE
- upstream_zero(vehicle, co2_grams_per_mile, kwh_per_mile)
Calculate upstream cert emissions under a “zero-upstream” policy.
- Parameters:
vehicle (Vehicle) – unused
co2_grams_per_mile (numeric value or array-like) – unused
kwh_per_mile (numeric value or array-like) – unused
- Returns:
Returns
0
- upstream_xev_ice_delta(vehicle, co2_grams_per_mile, kwh_per_mile)
Calculate upstream cert emissions based on cert direct kWh/mi relative to an ICE vehicle with the same target emissions. Upstream emissions cannot be negative.
upstream_co2e_g/mi = max(0, kwh_per_mile * upstream_gco2_per_kwh / upstream_efficiency - vehicle.target_co2e_grams_per_mile * upstream_gco2_per_gal / fuel_gco2_per_gal)
- Parameters:
vehicle (Vehicle) – The vehicle to calculate upstream emissions for
co2_grams_per_mile (numeric value or array-like) – vehicle cert direct CO2e g/mi
kwh_per_mile (numeric value or array-like) – vehicle cert direct kWh/mi
- Returns:
Upstream cert emissions based on kWh/mi relative to an ICE vehicle with the same target emissions
- upstream_actual(vehicle, co2_grams_per_mile, kwh_per_mile)
Calculate upstream cert emissions based on cert direct kWh/mi and CO2e g/mi.
upstream_co2e_g/mi = kwh_per_mile * upstream_gco2_per_kwh / upstream_efficiency + co2_grams_per_mile * upstream_gco2_per_gal / fuel_gco2_per_gal
- Parameters:
vehicle (Vehicle) – The vehicle to calculate upstream emissions for
co2_grams_per_mile (numeric value or array-like) – vehicle cert direct CO2e g/mi
kwh_per_mile (numeric value or array-like) – vehicle cert direct kWh/mi
- Returns:
Upstream cert emissions based on cert direct kWh/mi and CO2e g/mi
- class UpstreamMethods
Bases:
OMEGABase
Loads and provides access to upstream calculation methods by start year.
- static get_upstream_method(calendar_year)
Get the cert upstream calculation function for the given calendar year.
- Parameters:
calendar_year (int) – the calendar year to get the function for
- Returns:
A callable python function used to calculate upstream cert emissions for the given calendar year
- static init_from_file(filename, verbose=False)
Initialize class data from input file.
- Parameters:
filename (str) – name of input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
7.3.1.4.15. omega_model.policy.utility_factors module
Routines to load and apply utility factor calculation methods.
Calculate utility factor based on PHEV charge-depleting range
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows.
The data represents the calculation method(s) to apply by start year.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
utility_factor_methods
input_template_version:
0.1
- Sample Data Columns
start_year
city_method
city_norm_dist
highway_method
highway_norm_dist
0
FUF
583
FUF
583
2012
cityFUF
399
highwayFUF
399
2031
FUF
583
FUF
583
Data Column Name and Description
- start_year:
Start year of the upstream calculation method, method applies until the next available start year
- city_method:
Method name to call for calculating ‘city’ (FTP) utility factor
- city_norm_dist:
Normalizing distance to use in calculating ‘city’ utility factor
- highway_method:
Method name to call for calculating ‘highway’ (HWFET, US06) utility factor
- highway_norm_dist:
Normalizing distance to use in calculating ‘highway’ utility factor
CODE
- labelUF(miles, norm_dist=400)
Calculate “label” PHEV individual vehicle utility factor, from SAEJ2841 SEP2010. https://www.sae.org/standards/content/j2841_201009/
- Parameters:
miles – distance travelled in charge-depleting driving, scalar or pandas Series
norm_dist – distance normalizing denominator in miles
- Returns:
Utility factor from SAEJ2841 SEP2010, Table 2 (Multi-day utility factor Fit)
- cityFUF(miles, norm_dist=399)
Calculate “city” PHEV fleet utility factor, from SAEJ2841 SEP2010. https://www.sae.org/standards/content/j2841_201009/
- Parameters:
miles – distance travelled in “city” charge-depleting driving, scalar or pandas Series
norm_dist – distance normalizing denominator in miles
- Returns:
City utility factor from SAEJ2841 SEP2010, Table 5 (55/45 city/highway split)
- highwayFUF(miles, norm_dist=399)
Calculate “highway” PHEV fleet utility factor, from SAEJ2841 SEP2010. https://www.sae.org/standards/content/j2841_201009/
- Parameters:
miles – distance travelled in “highway” charge-depleting driving, scalar or pandas Series
norm_dist – distance normalizing denominator in miles
- Returns:
Highway utility factor from SAEJ2841 SEP2010, Table 5 (55/45 city/highway split)
- FUF(miles, norm_dist=399)
Calculate PHEV fleet utility factor, from SAEJ2841 SEP2010. https://www.sae.org/standards/content/j2841_201009/
- Parameters:
miles – distance travelled in charge-depleting driving, scalar or pandas Series
norm_dist – distance normalizing denominator in miles
- Returns:
Fleet Utility Factor from SAEJ2841 SEP2010, Table 2
- class UtilityFactorMethods
Bases:
OMEGABase
Loads and provides access to upstream calculation methods by start year.
- static calc_city_utility_factor(calendar_year, miles)
Calculate “city” PHEV fleet utility factor
- Parameters:
calendar_year (int) – the calendar year to get the function for
miles – distance travelled in charge-depleting driving, scalar or pandas Series
- Returns:
A callable python function used to calculate upstream cert emissions for the given calendar year
- static calc_highway_utility_factor(calendar_year, miles)
Calculate “highway” PHEV fleet utility factor
- Parameters:
calendar_year (int) – the calendar year to get the function for
miles – distance travelled in charge-depleting driving, scalar or pandas Series
- Returns:
A callable python function used to calculate upstream cert emissions for the given calendar year
- static init_from_file(filename, verbose=False)
Initialize class data from input file.
- Parameters:
filename (str) – name of input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
7.3.1.4.16. omega_model.policy.workfactor_definition module
Loads parameters and provides calculations for calculating the work factor.
This is based on the current work factor based standards, with two liquid fuel types and with lifetime VMT and parameter-based target calculations based on work factor with work factor defined in the work_factor_definition file.
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows. The template header uses a dynamic format.
The data represent the work factor calculation based on drive system (e.g., 2wd, 4wd) and weigh characteristics.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
workfactor_definition
input_template_version:
0.1
- Sample Data Columns
start_year
drive_system
xwd
workfactor
2014
2
0
(0.75) * (gvwr_lbs - curbweight_lbs + xwd) + 0.25 * (gcwr_lbs - gvwr_lbs)
2014
4
500
(0.75) * (gvwr_lbs - curbweight_lbs + xwd) + 0.25 * (gcwr_lbs - gvwr_lbs)
Data Column Name and Description
- start_year:
The start year of the standard, applies until the next available start year
- drive_system:
2-wheel drive (2) or 4-wheel drive (4)
- xwd:
The weight adjustment associated with drive system
- work_factor:
The calculation for work factor
CODE
- class WorkFactor
Bases:
OMEGABase
Work factor definition and calculations.
- start_years = {}
dict of start years by drive system type
- static calc_workfactor(model_year, curbweight_lbs, gvwr_lbs, gcwr_lbs, drive_system)
Calculate vehicle workfactor.
- Parameters:
model_year (int) – vehicle model year
curbweight_lbs (float) – vehicle curb weight in lbs
gvwr_lbs (float) – vehicle gross vehicle weight rating in lbs
gcwr_lbs (float) – vehicle combined weight rating in lbs
drive_system (int) – drive system, 2=two wheel drive, 4=four wheel drive, etc
- Returns:
Vehicle workfactor.
- static init_from_file(filename, verbose=False)
Initialize class data from input file.
- Parameters:
filename (str) – name of input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
7.3.1.5. omega_model.producer package
OMEGA producer subpackage.
CODE
7.3.1.5.1. Submodules
7.3.1.5.2. omega_model.producer.compliance_search module
Compliance strategy implements the producer search algorithm to find a low-cost combination of technologies (via vehicle CO2e g/mi) and market shares that achieve a targeted certification outcome.
CODE
- error_callback(e)
Print multiprocess error callback to the console.
- Parameters:
e (BaseException) – exception info
- create_tech_sweeps(composite_vehicles, candidate_production_decisions, share_range)
Create tech sweeps is responsible for creating tech (CO2e g/mi levels) options to develop a set of candidate compliance outcomes for the manufacturer in the given year as a function of the active policy.
Called from
search_production_options()
.The combination of shares (to determine vehicle sales) and g/mi levels determines the CO2e Mg compliance outcome of each option outside of this function.
On the first pass through this function, there are no
candidate_production_decisions
so the result of the first pass is effectively unconstrained (in the absence of required minimum production levels or production constraints).On the second pass, the producer has chosen one or more candidate production options from the prior cloud of choices, the share range is compressed based on the
producer_compliance_search_convergence_factor
setting. Subsequent tech options will be generated around thecandidate_production_decisions
.Calls from
search_production_options()
continue with subsequently tighter share ranges until the compliance target has been met within a tolerance. Ultimately a single candidate production decision is selected and passed to the consumer which reacts to the generalized cost of each option with a desired market share.- Parameters:
composite_vehicles ([CompositeVehicle]) – the list of producer composite vehicles
candidate_production_decisions (None, DataFrame) – zero or 1 or 2 candidate production decisions chosen from the results of the previous search iteration
share_range (float) – determines the numerical range of share and tech options that are considered
- Returns:
A dataframe containing a range of composite vehicle CO2e g/mi options factorially combined
- round_constraints(constraints, min_val=0.0, max_val=1.0)
Round constraints to some reasonable number of decimal places
- Parameters:
constraints (dict) – constraints dict
min_val (float) – minimum allowed value
max_val (float) – maximum allowed value
- Returns:
Nothing, updates constraints dict.
Create share sweeps is responsible for creating market share options to develop a set of candidate compliance outcomes for the manufacturer in the given year as a function of the active policy. The function recursively navigates the
market_class_dict
as a tree of market categories.Called from
search_production_options()
.The combination of shares (to determine vehicle sales) and g/mi levels determines the CO2e Mg compliance outcome of each option outside of this function.
On the first pass through this function, there are no
candidate_production_decisions
and there is not yet aconsumer_response
to those production decisions so the result of the first pass is effectively unconstrained (in the absence of required minimum production levels or production constraints).On the second pass, the producer has chosen one or more candidate production options from the prior cloud of choices, the share range is compressed based on the
producer_compliance_search_convergence_factor
setting. Subsequent market shares will be generated around thecandidate_production_decisions
.Calls from
search_production_options()
continue with subsequently tighter share ranges until the compliance target has been met within a tolerance. Ultimately a single candidate production decision is selected and passed to the consumer which reacts to the generalized cost of each option with a desired market share.If none of the outcomes are within the market share convergence tolerance then subsequent calls to this function include the
consumer_response
and are used as to generate nearby market share options, again as a function of theshare_range
as the producer continues to search compliance options.- Parameters:
calendar_year (int) – the year in which the compliance calculations take place
market_class_dict (dict) – a dict of CompositeVehicle object lists hiearchically grouped by market categories into market classes
candidate_production_decisions (None, DataFrame) – zero or 1 or 2 candidate production decisions chosen from the results of the previous search iteration
share_range (float) – determines the numerical range of share and tech options that are considered
consumer_response (Series) – a pandas Series containing the final producer decision from prior iterations and containing the consumer desired market shares based on that decision and the producer’s cross-subsidy, if any
context_based_total_sales (float) – context-based total vehicle sales for the given year
prior_producer_decision_and_response (Series) – prior-year producer decision and response
producer_consumer_iteration_num (int) – producer-consumer iteration number
node_name (str) – name of the node in the
market_class_dict
, used to traverse the market class treeverbose (bool) – enables additional console output if
True
- Returns:
A dataframe containing a range of market share options factorially combined
- apply_production_decision_to_composite_vehicles(composite_vehicles, selected_production_decision)
Apply the selected production decision to the given composite vehicles (g/mi results and sales) and decompose the composite values down to the source vehicles. Update the composite vehicle CO2e Mg and cost values based on the weighted values of the source vehicles.
- Parameters:
composite_vehicles (list) – list of
CompositeVehicle
objectsselected_production_decision (Series) – the production decision as a result of the compliance search
- Returns:
A list of updated CompositeVehicle` objects
- search_production_options(compliance_id, calendar_year, producer_decision_and_response, producer_consumer_iteration_num, strategic_target_offset_Mg, prior_producer_decision_and_response)
This function implements the producer search for a set of technologies (CO2e g/mi values) and market shares that achieve a desired compliance outcome taking into consideration the strategic target offset which allows intentional under- or over-compliance based on the producer’s credit situation, for example.
This function is called from
omega.run_producer_consumer()
.On the first pass through, there is no
producer_decision_and_response
yet. On subsequent iterations (producer_consumer_iteration_num
> 0) the producer decision and consumer response is used to constrain the range of market shares under consideration by the producer.- Parameters:
compliance_id (str) – manufacturer name, or ‘consolidated_OEM’
calendar_year (int) – the year of the compliance search
producer_decision_and_response (Series) – pandas Series containing the producer’s selected production decision from the prior iteration and the consumer’s desired market shares
producer_consumer_iteration_num (int) – the number of the producer-consumer iteration
strategic_target_offset_Mg (float) – if positive, the raw compliance outcome will be under-compliance, if negative then the raw compliance outcome will be over-compliance. Used to strategically under- or over- comply, perhaps as a result of the desired to earn or burn prior credits in the credit bank
prior_producer_decision_and_response (Series) – prior-year producer decision and response
- Returns:
A tuple of
composite_vehicles
(list of CompositeVehicle objects),selected_production_decision
(pandas Series containing the result of the serach),market_class_tree
(dict of CompositeVehicle object lists hiearchically grouped by market categories into market classes), andproducer_compliance_possible
(bool that indicates whether compliance was achievable)
- calc_composite_vehicle(mc, rc, alt, mctrc)
Calculate composite vehicle for the set of vehicles in the given market class / reg class / alt class
- Parameters:
mc (str) – market classs id, e.g. ‘hauling.ICE’
rc (str) – regulatory class, e.g. ‘car’, ‘truck’
alt (str) – ‘ALT’ or ‘NO_ALT’
mctrc (dict) – market-class/reg-clas tree
- Returns:
The composite vehicle for the set of vehicles in the given market class / reg class / alt class
- create_composite_vehicles(calendar_year, compliance_id)
Create composite vehicles based on the prior year’s finalized vehicle production and update the sales mix based on projections from the context and caclulate this year’s nominal sales for the compliance ID based on the context.
- Parameters:
calendar_year (int) – the year of the compliance search
compliance_id (str) – manufacturer name, or ‘consolidated_OEM’
- Returns:
tuple
composite_vehicles
(list of CompositeVehicle objects),market_class_tree
(dict of CompositeVehicle object lists hiearchically grouped by market categories into market classes),context_based_total_sales
(total vehicle sales based on the context for the givencompliance_id
)
- finalize_production(calendar_year, compliance_id, candidate_mfr_composite_vehicles, pre_production_vehicles, producer_decision)
Finalize vehicle production at the conclusion of the compliance search and producer-consumer market share iteration. Manufacturer Annual Data is updated with the certification results in CO2e Mg
- Parameters:
calendar_year (int) – the year of the compliance search
compliance_id (str) – manufacturer name, or ‘consolidated_OEM’
candidate_mfr_composite_vehicles (list) – list of
CompositeVehicle
objectspre_production_vehicles (list) – list of the vehicles that have not entered production yet
producer_decision (Series) – the production decision as a result of the compliance search
- Returns:
Nothing, updates the OMEGA data with the finalized vehicles
- decompose_candidate_vehicles(candidate_mfr_composite_vehicles, producer_decision)
Propagate sales to source vehicles and interpolate cost curve data.
- Parameters:
candidate_mfr_composite_vehicles (list) – list of
CompositeVehicle
objectsproducer_decision (Series) – the production decision as a result of the compliance search
- Returns:
Nothing, updates composite vehicles.
See also
producer.vehicles.CompositeVehicle.decompose()
Create a set of production options, including compliance outcomes, based on the given tech and share combinations.
On the first time through, from the
producer
module, total_sales is based on context, market shares come from the producer desired market shares.On the second time through, from the
omega
module, total_sales is determined by sales response, market shares come from the consumer demanded market shares.- Parameters:
composite_vehicles (list) – list of
CompositeVehicle
objectstech_and_share_combinations (DataFrame) – the result of
create_tech_and_share_sweeps()
total_sales (float) – manufacturer total vehicle sales based on the context or the consumer response
- Returns:
production_options
DataFrame of technology and share options including compliance outcomes in CO2e Mg
- select_candidate_manufacturing_decisions(production_options, calendar_year, search_iteration, producer_iteration_log, strategic_target_offset_Mg)
Select candidate manufacturing decisions from the cloud of production options. If possible, there will be two candidates, one on either side of the compliance target. If not possible then the closest option will be selected.
- Parameters:
production_options (DataFrame) – dataframe of the production options, including compliance outcomes in Mg
calendar_year (int) – the calendar year of the production options
search_iteration (int) – the iteration number of the compliance search
producer_iteration_log (IterationLog) – used to optionally log the production options based on developer settings
strategic_target_offset_Mg (float) – if positive, the raw compliance outcome will be under-compliance, if negative then the raw compliance outcome will be over-compliance. Used to strategically under- or over- comply, perhaps as a result of the desired to earn or burn prior credits in the credit bank
- Returns:
tuple
candidate_production_decisions
(the best available production decisions),compliance_possible
(bool indicating whether compliance was possible)
- cull_compliant_points(compliant_tech_share_options, prior_most_strategic_compliant_tech_share_option)
Remove compliant points that aren’t as good as the prior most strategic compliant point.
- Parameters:
compliant_tech_share_options (dataframe) – compliant tech share options
prior_most_strategic_compliant_tech_share_option (series) – prior most strategic compliant tech share option if any,
None
otherwise
- Returns:
compliant_tech_share_options
with non-optimal points removed
- cull_non_compliant_points(non_compliant_tech_share_options, prior_most_strategic_non_compliant_tech_share_option)
Remove non-compliant points that aren’t as good as the prior most strategic non-compliant point.
- Parameters:
non_compliant_tech_share_options (dataframe) – non-compliant tech share options
prior_most_strategic_non_compliant_tech_share_option (series) – prior most strategic non-compliant tech share option if any,
None
otherwise
- Returns:
non_compliant_tech_share_options
with non-optimal points removed
7.3.1.5.3. omega_model.producer.manufacturer_annual_data module
Routines to create and update yearly manufacturer compliance data.
Manufacturer annual data is created for each compliance model year as a result of vehicle sales and certification performance. Compliance of a model year may be achieve retroactively through the use of credits created by future model years.
See also
The GHG_credits
module, and postproc_session.plot_manufacturer_compliance()
for credit plotting routines.
CODE
- class ManufacturerAnnualData
Bases:
OMEGABase
Stores manufacturer annual target / achieved CO2e Mg and total cost data.
- static create_manufacturer_annual_data(model_year, compliance_id, target_co2e_Mg, calendar_year_cert_co2e_Mg, manufacturer_vehicle_cost_dollars, model_year_cert_co2e_megagrams=None)
Create initial manufacturer compliance entry for the given year. Final compliance state may depend on future years via credit banking.
- Parameters:
model_year (numeric) – the compliance model year
compliance_id (str) – manufacturer name, or ‘consolidated_OEM’
target_co2e_Mg (numeric) – target CO2e Mg for the model year
calendar_year_cert_co2e_Mg (numeric) – initial compliance state (CO2e Mg) of the vehicles produced in the model year
manufacturer_vehicle_cost_dollars (numeric) – total manufacturer vehicle cost (sum of vehicle sales X vehicle cost)
model_year_cert_co2e_megagrams (numeric) – manufacturer model year cert CO2e Mg, if known, else
None
- Returns:
Nothing, updates class data
- static get_target_co2e_Mg(compliance_id)
Get cert target CO2e in megagrams for each model year.
- Parameters:
compliance_id (str) – manufacturer name, or ‘consolidated_OEM’
Returns: A list of target CO2e Mg for each model year
- static get_calendar_year_cert_co2e_Mg(compliance_id)
Get the initial cert CO2e in megagrams for each calendar year, final certification may be higher or lower depending on credit transfers.
- Parameters:
compliance_id (str) – manufacturer name, or ‘consolidated_OEM’
Returns: A list of initial compliance state data (CO2e Mg) of the vehicles produced by model year
- static get_model_year_cert_co2e_Mg(compliance_id)
Get the final cert CO2e in megagrams for each model year, including the effect of credit transfers.
- Parameters:
compliance_id (str) – manufacturer name, or ‘consolidated_OEM’
Returns: A list of final achieved certification CO2e Mg for each model year, including credits transferred to/from other model years
- static get_total_cost_billions(compliance_id)
Get total manufacturer new vehicle cost (sum of vehicle prices times vehicle sales) for each model year, in billions of dollars.
- Parameters:
compliance_id (str) – manufacturer name, or ‘consolidated_OEM’
Returns: A list of total manufacturer vehicle costs by model year, in billions of dollars
- static update_model_year_cert_co2e_Mg(model_year, compliance_id, transaction_amount_Mg)
Update model year certification CO2e Mg based on the given transaction amount. Used for credit banking.
- Parameters:
model_year (numeric) – the model year of the transaction
compliance_id (str) – manufacturer name, or ‘consolidated_OEM’
transaction_amount_Mg (numeric) – the transaction amount, may be positive (receiving credits) or negative (transferring credits)
- static init_manufacturer_annual_data()
Initialize the module by clear caches.
- Returns:
Nothing, clears cached data.
7.3.1.5.4. omega_model.producer.manufacturers module
Routines to load manufacturer definition data.
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows.
The data represents manufacturer names.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
manufacturers
input_template_version:
0.0003
description:
default
- Sample Data Columns
manufacturer_id
consolidated_OEM
OEM_A
OEM_B
Data Column Name and Description
- manufacturer_id:
The name of the manufacturer
CODE
- class Manufacturer
Bases:
OMEGABase
Stores information regarding manufacturers, such as manufacturer ID.
- manufacturers = []
stores a list of manufacturer names after init
- static update_market_class_data(manufacturer_id, market_class_id)
Add the given market class id to the market class data for the given manufacturer.
- Parameters:
manufacturer_id (str) – e.g. ‘consolidated_OEM’
market_class_id (str) – e.g. ‘hauling.ICE’
- Returns:
Nothing, updates market_class_data
- static init_from_file(filename, verbose=False)
Initialize class data from input file.
- Parameters:
filename (str) – name of input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
7.3.1.5.5. omega_model.producer.producer_base_classes module
A set of base classes used to define the program interface(s) and to serve as templates for user-defined classes
Ordinarily these classes might be implemented as Python abstract classes but abstract classes cause issues when combined with SQLAlchemy base classes, so the implementation here is a workaround - if a child class fails to implement one of the required methods, the class will throw a runtime Exception or return an error message.
- class ProducerGeneralizedCostBase
Bases:
object
Loads producer generalized cost data and provides cost calculation functionality.
- static get_producer_generalized_cost_attributes(market_class_id, attribute_types)
Get one or more producer generalized cost attributes associated with the given market class ID.
- Parameters:
market_class_id (str) – market class id, e.g. ‘hauling.ICE’
attribute_types (str, [strs]) – name or list of generalized cost attribute(s), e.g.
['producer_generalized_cost_fuel_years', 'producer_generalized_cost_annual_vmt']
- Returns:
The requested generalized cost attributes.
- static calc_generalized_cost(vehicle, cost_cloud, co2_name, kwh_name, cost_name)
Calculate generalized cost (vehicle cost plus other costs such as fuel costs) for the given vehicle’s cost cloud.
- Parameters:
vehicle (Vehicle) – the vehicle to calculate generalized costs for
cost_cloud (dataframe) – the vehicle’s cost cloud
co2_name (str) – CO2 column name, e.g. ‘onroad_direct_co2e_grams_per_mile’
kwh_name (str) – kWh/mi column name, e.g. ‘onroad_direct_kwh_per_mile’
cost_name (str) – vehicle cost column name, e.g. ‘new_vehicle_mfr_cost_dollars’
- Returns:
The vehicle’s cost cloud with generalized cost column, e.g. ‘new_vehicle_mfr_generalized_cost_dollars’
- static init_from_file(filename, verbose=False)
Initialize class data from input file.
- Parameters:
filename (str) – name of input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
7.3.1.5.6. omega_model.producer.producer_generalized_cost module
Routines to implement producer generalized cost calculations.
INPUT FILE FORMAT
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows. The template header uses a dynamic format.
The data represents producer generalized cost parameters by market class ID.
- File Type
comma-separated values (CSV)
- Template Header
input_template_name:
[module_name]
input_template_version:
[template_version]
- Sample Header
input_template_name:
producer.producer_generalized_cost
input_template_version:
0.1
- Sample Data Columns
market_class_id
fuel_years
annual_vmt
non_hauling.BEV
5
15000
hauling.ICE
5
15000
Data Column Name and Description
- market_class_id:
Vehicle market class ID, e.g. ‘hauling.ICE’
- fuel_years:
Number of years of fuel cost to include in producer generalized cost
- annual_vmt:
Annual vehicle miles travelled for calculating producer generalized cost
CODE
- class ProducerGeneralizedCost
Bases:
OMEGABase
,ProducerGeneralizedCostBase
Loads producer generalized cost data and provides cost calculation functionality.
- static get_producer_generalized_cost_attributes(market_class_id, attribute_types)
Get one or more producer generalized cost attributes associated with the given market class ID.
- Parameters:
market_class_id (str) – market class id, e.g. ‘hauling.ICE’
attribute_types (str, [strs]) – name or list of generalized cost attribute(s), e.g.
['producer_generalized_cost_fuel_years', 'producer_generalized_cost_annual_vmt']
- Returns:
The requested generalized cost attributes.
- static calc_generalized_cost(vehicle, cost_cloud, co2_name, kwh_name, cost_name)
Calculate generalized cost (vehicle cost plus other costs such as fuel costs) for the given vehicle’s cost cloud.
- Parameters:
vehicle (Vehicle) – the vehicle to calculate generalized costs for
cost_cloud (DataFrame) – vehicle cost cloud
co2_name (str) – CO2 column name, e.g. ‘onroad_direct_co2e_grams_per_mile’
kwh_name (str) – kWh/mi column name, e.g. ‘onroad_direct_kwh_per_mile’
cost_name (str) – vehicle cost column name, e.g. ‘new_vehicle_mfr_cost_dollars’
- Returns:
The vehicle’s cost cloud with generalized cost column, e.g. ‘new_vehicle_mfr_generalized_cost_dollars’
- static init_from_file(filename, verbose=False)
Initialize class data from input file.
- Parameters:
filename (str) – name of input file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
7.3.1.5.7. omega_model.producer.vehicle_aggregation module
Routines to load base-year vehicle data, data structures to represent vehicles during compliance modeling (transient or ephemeral vehicles), finalized vehicles (manufacturer-produced compliance vehicles), and composite vehicles (used to group vehicles by various characteristics during compliance modeling).
Classes are also implemented to handle composition and decomposition of vehicle attributes as part of the composite vehicle workflow. Some vehicle attributes are known and fixed in advance, others are created at runtime (e.g. off-cycle credit attributes which may vary by policy).
INPUT FILE FORMAT (Vehicles File)
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows.
The data represents base-year vehicle attributes and sales.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
vehicles
input_template_version:
0.51
notes:
From 0904. Rev 1211, Maserati now in Stellantis
- Sample Data Columns
vehicle_name
manufacturer_id
model_year
reg_class_id
context_size_class
electrification_class
cost_curve_class
in_use_fuel_id
cert_fuel_id
sales
footprint_ft2
eng_rated_hp
battery_gross_kwh
tractive_motor_kw
total_emachine_kw
onroad_charge_depleting_range_mi
tot_road_load_hp
etw_lbs
length_in
width_in
height_in
ground_clearance_in
wheelbase_in
interior_volume_cuft
msrp_dollars
passenger_capacity
payload_capacity_lbs
towing_capacity_lbs
unibody_structure
body_style
structure_material
prior_redesign_year
redesign_interval
drive_system
alvw_lbs
gvwr_lbs
gcwr_lbs
curbweight_lbs
dual_rear_wheel
long_bed_8ft
engine_cylinders
engine_displacement_liters
target_coef_a
target_coef_b
target_coef_c
application_id
DB11 V12
Aston Martin Lagonda
2022
car
Minicompact
N
ICE_SLA_RWD_TDS_TRX21R_SS0
{‘pump gasoline’:1.0}
gasoline
16
50
630
14.6
4500
110.4
233200
1
sedan
steel
2017
5
RWD
0
12
5.2
40.94
0.0169
0.0271
SLA
GRAND WAGONEER 4X4
Stellantis
2022
truck
Large Crossover
N
ICE_HLA_AWD_GDI_DEAC_D_TRX21R_SS0
{‘pump gasoline’:1.0}
gasoline
14728
58.6
471
21.39841471
6500
123
35350
1
cuv_suv
steel
2016
5
AWD
0
8
6.4
66.03
-0.0009
0.03824
HLA
MODEL Y LONG RANGE AWD
Tesla
2022
truck
Large Crossover
EV
BEV_AWD
{‘US electricity’:1.0}
electricity
130272
51.1
0
80.5
200
291
330
11.4
4750
113.8
50490
1
cuv_suv
steel
2012
5
AWD
0
0
0
34.26
0.3191
0.0142
SLA
Data Column Name and Description
REQUIRED COLUMNS
- vehicle_name:
The vehicle name or description, e.g. ‘ICE Small Utility truck’, ‘BEV Subcompact car’, etc
- manufacturer_id:
Manufacturer name, must be consistent with the data loaded by
class manufacturers.Manufacturer
- model_year:
The model year of the vehicle data, e.g. 2020
- reg_class_id:
Vehicle regulatory class at the time of certification, e.g. ‘car’,’truck’. Reg class definitions may differ across years within the simulation based on policy changes.
reg_class_id
can be considered a ‘historical’ or ‘legacy’ reg class.- context_size_class:
The context size class of the vehicle, for future sales mix projections. Must be consistent with the context input file loaded by
class context_new_vehicle_market.ContextNewVehicleMarket
- electrification_class:
The electrification class of the vehicle, such as ‘EV’, ‘HEV’, (or ‘N’ for none - final format TBD)
- cost_curve_class:
The name of the cost curve class of the vehicle, used to determine which technology options and associated costs are available to be applied to this vehicle. Must be consistent with the data loaded by
class cost_clouds.CostCloud
- in_use_fuel_id:
In-use fuel id, for use with context fuel prices, must be consistent with the context data read by
class context_fuel_prices.ContextFuelPrices
- cert_fuel_id:
Certification fuel id, for determining certification upstream CO2e grams/mile, must be in the table loaded by
class policy.policy_fuels.PolicyFuel
- sales:
Number of vehicles sold in the
model_year
- footprint_ft2:
Vehicle footprint based on vehicle wheelbase and track (square feet)
- eng_rated_hp:
Vehicle engine rated power (horsepower)
- battery_gross_kwh:
Propulsion battery gross capacity (kWh)
- tractive_motor_kw:
Tractive motor rated power (kW)
- total_emachine_kw:
Total emachine rated power: tractive motor(s) + generator(s) (kW)
- onroad_charge_depleting_range_mi:
Onroad charge depleting range (miles)
- unibody_structure:
Vehicle body structure; 1 = unibody, 0 = body-on-frame
- drive_system:
Vehicle drive system, ‘FWD’, ‘RWD’, ‘AWD’
- dual_rear_wheel:
= 1 if vehicle has dual rear wheels, i.e. ‘duallies’, = 0 otherwise
- curbweight_lbs:
Vehicle curb weight (pounds)
- gvwr_lbs:
Gross Vehicle Weight Rating (pounds)
- gcwr_lbs:
Gross Combined Weight Rating (pounds)
- target_coef_a:
Coast down target A coefficient (lbf)
- target_coef_b:
Coast down target B coefficient (lbf/mph)
- target_coef_c:
Coast down target C coefficient (lbf/mph**2)
- body_style:
Vehicle body style; sedan, cuv_suv, pickup
- msrp_dollars:
Vehicle manufacturer suggested retail price (MSRP)
- structure_material:
Primary material of the body structure; steel, aluminum
- prior_redesign_year:
The vehicle’s prior redesign year
- redesign_interval:
The vehicle’s redesign interval, in years
- engine_cylinders:
Number of engine cylinders
- engine_displacement_liters:
Engine displacement (liters)
- application_id:
‘SLA’ = Standard Load Application, ‘HLA’ = High Load Application, ‘MDV’ = Medium-duty Vehicle
- OPTIONAL COLUMNS
These columns become object attributes that may be used to determine vehicle regulatory class (e.g. ‘car’,’truck’) based on the simulated policy, or they may be used for other purposes.
- tot_road_load_hp:
Vehicle roadload power (horsepower) at a vehicle speed of 50 miles per hour
- etw_lbs:
Vehicle equivalent test weight (ETW) (pounds)
- cert_direct_oncycle_co2e_grams_per_mile:
Vehicle certification emissions CO2e grams/mile
- cert_direct_oncycle_kwh_per_mile:
Vehicle certification electricity consumption kWh/mile
- length_in:
Vehicle overall length (inches)
- width_in:
Vehicle overall width (inches)
- height_in:
Vehicle overall height (inches)
- ground_clearance_in:
Vehicle ground clearance (inches)
- wheelbase_in:
Vehicle wheelbase (inches)
- interior_volume_cuft:
Vehicle interior volume (cubic feet)
- passenger_capacity:
Vehicle passenger capacity (number of occupants)
- payload_capacity_lbs:
Vehicle payload capacity (pounds)
- towing_capacity_lbs:
Vehicle towing capacity (pounds)
- alvw_lbs:
Average loaded vehicle weight (pounds)
- long_bed_8ft:
= 1 if pickup truck has an 8’ long bed
—
CODE
- class VehicleAggregation
Bases:
OMEGABase
Implements aggregation of detailed vehicle data into compliance vehicles.
- __init__()
- static init_from_file(filename, verbose=False)
Validate and read detailed vehicles.csv file
- Parameters:
filename (str) – the name of the base year vehicles file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
# See Also: #
DecompositionAttributes
- static weighted_fillna(df, col, weight_by='sales', update_df=True)
Fill NaNs (if any) with weighted value
- Parameters:
df (DataFrame) – the dataframe to fill
col (str) – name of column to fill
weight_by (str) – name of the weighting column
update_df (bool) – if
True
then df will get updated values
- Returns:
Nothing, modifies df[col] by filling NaNs with weighted value
7.3.1.5.8. omega_model.producer.vehicle_annual_data module
Vehicle annual data module.
Routines to store and retrieve vehicle annual data, which includes age, registered count, vehicle miles travelled, etc.
CODE
- class VehicleAnnualData
Bases:
OMEGABase
Stores and retrieves vehicle annual data, which includes age, registered count, vehicle miles travelled, etc.
- static create(calendar_year, vehicle_id, compliance_id, age, reg_class_id, registered_count=0, annual_vmt=0, odometer=0, vmt=0)
Create a dict of the given values.
- Parameters:
calendar_year (int) – the calendar year
vehicle_id (str) – the vehicle id
compliance_id (str) – manufacturer name, or ‘consolidated_OEM’
age (int) – vehicle age in years
reg_class_id (str) – reg class id, e.g. ‘car’, ‘truck’, etc
registered_count (float) – the registered count of the given vehicle
annual_vmt (float) – annual vehicle miles travelled
odometer (float) – the accumulate vehicle miles travelled of the given vehicle
vmt (float) – vehicle miles travelled
- Returns:
A dict of the given values.
- static add_all(vad_list)
Add all vehicle annual data records to the class data set.
- Parameters:
vad_list (dict | list) – dict or list of vehicle annual data dicts
- Returns:
Nothing, updates
VehicleAnnualData._data
- static update_registered_count(vehicle, calendar_year, registered_count)
Update vehicle registered count and / or create initial vehicle annual data table entry.
- Parameters:
vehicle (Vehicle) – the vehicle whose count is being updated
calendar_year (int) – the calendar year to update registered count it
registered_count (float) – number of vehicle that are still in service (registered)
- Returns:
Nothing, updates vehicle annual data table
- static get_calendar_years()
Get the calendar years that have vehicle annual data.
- Returns:
List of calendar years that have vehicle annual data.
- static get_vehicle_annual_data(calendar_year, compliance_id=None, attributes=None)
Get vehicle annual data for the given calendar year and compliance id, if applicable.
- Parameters:
calendar_year (int) – calendar to get data for
compliance_id (str) – name of manufacturer, e.g. ‘consolidated_OEM’
attributes (str, [strs]) – optional name of attribute(s) to retrieve instead of all data
- Returns:
A list of VehicleAnnualData dictionaries``
- static get_vehicle_annual_data_by_vehicle_id(calendar_year, vehicle_id, attribute_name)
Get vehicle annual data for the given calendar year.
- Parameters:
calendar_year (int) – calendar to get data for
vehicle_id (str) – the vehicle_id
attribute_name (str) – the attribute_name for which a value is sought
- Returns:
The attribute_value for the given attribute_name
- static init_vehicle_annual_data()
Initialize the module by clear caches.
- Returns:
Nothing, clears cached data.
7.3.1.5.9. omega_model.producer.vehicles module
Routines to load base-year vehicle data, data structures to represent vehicles during compliance modeling (transient or ephemeral vehicles), finalized vehicles (manufacturer-produced compliance vehicles), and composite vehicles (used to group vehicles by various characteristics during compliance modeling).
Classes are also implemented to handle composition and decomposition of vehicle attributes as part of the composite vehicle workflow. Some vehicle attributes are known and fixed in advance, others are created at runtime (e.g. off-cycle credit attributes which may vary by policy).
INPUT FILE FORMAT (Onroad Vehicle Calculations File)
The file format consists of a one-row template header followed by a one-row data header and subsequent data rows. The data header uses a dynamic column notation, as detailed below.
The data represents the “gap” between on-cycle and onroad GHG performance.
- File Type
comma-separated values (CSV)
- Sample Header
input_template_name:
onroad_vehicle_calculations
input_template_version:
0.22
notes:
20221028a FTP US06 for w no gap for onroad and 2cycle w BEV 0.75 adjust for battery sizing
The data header consists of a drive_cycle_weight_year
column followed by calculation columns.
- Dynamic Data Header
drive_cycle_weight_year
{vehicle_select_attribute}:{vehicle_select_attribute_value}:{operator}:{vehicle_source_attribute}->{vehicle_destination_attribute}
…
- Sample Data Columns
onroad_drive_cycle_weight_year
battery_sizing_drive_cycle_weight_year
fueling_class:BEV:/:nominal_onroad_direct_kwh_per_mile->battery_sizing_onroad_direct_kwh_per_mile
fueling_class:BEV:/:nominal_onroad_direct_kwh_per_mile->onroad_direct_kwh_per_mile
fueling_class:ICE:/:nominal_onroad_direct_co2e_grams_per_mile->onroad_direct_co2e_grams_per_mile
0
2012
0.75
1
1
Data Column Name and Description
- onroad_drive_cycle_weight_year:
Year to use for cert drive cycle weight calculations
- battery_sizing_drive_cycle_weight_year:
Year to use for battery sizing drive cycle weight calculations
Optional Columns
Subsequent columns have the format {vehicle_select_attribute}:{vehicle_select_attribute_value}:{operator}: {vehicle_source_attribute}->{vehicle_destination_attribute}, the row value is a numeric value to applied to the source attribute to calculate the destination attribute.
For example, a fueling_class:BEV:/:cert_direct_kwh_per_mile->onroad_direct_kwh_per_mile
column with a row value of
0.7
would be evaluated as:
if vehicle.fueling_class == 'BEV': vehicle.onroad_direct_kwh_per_mile = vehicle.cert_direct_kwh_per_mile / 0.7
CODE
- class DecompositionAttributes
Bases:
OMEGABase
Stores vehicle-specific attributes that will be tracked at each point of a vehicle or composite vehicle frontier
Decomposition Attributes are interpolated from the composite vehicle frontier during decomposition, using composite vehicle cert_co2e_grams_per_mile
- values = []
list of all decomposition attribute names
- offcycle_values = []
list of off cycle credits that in the simulated vehicle file AND in the off cycle credits intput file
- other_values = []
non-base, non-offcycle, non-drive-cycle attribute names from the simulated vehicles input file, e.g. tech application columns like cooled EGR, etc
- classmethod init()
Initialize DecompositionAttributes.
- Returns:
Nothing, updates class data regarding available decomposition attibutes
- static interp1d(vehicle, cost_curve, index_column, index_value, attribute_name)
Interpolate the given cost curve using the given index column name, index value(s), vehicle and attribute name.
- Parameters:
vehicle (Vehicle or CompositeVehicle) – the vehicle object
cost_curve (DataFrame) – the cost curve to interpolate
index_column (str) – the name of the x-axis / index column
index_value (numeric) – the x-axis / index value(s) at which to interpolate
attribute_name (str) – name of the attribute to interpolate
- Returns:
A float or numeric Array of values and each index value
- static interp1d_non_numeric(vehicle, cost_curve_non_numeric_data, index_column, index_value, attribute_name)
Interpolate non-numeric data
- Parameters:
vehicle (Vehicle or CompositeVehicle) – the vehicle object
cost_curve_non_numeric_data (DataFrame) – the cost curve non-numeric data to interpolate
index_column (str) – the name of the x-axis / index column
index_value (numeric) – the x-axis / index value(s) at which to interpolate
attribute_name (str) – name of the attribute to interpolate
- Returns:
None, updates vehicle attributes based on interpolation
- classmethod rename_decomposition_columns(vehicle, cost_curve)
Rename the cost curve decomposition columns from non-vehicle specific to vehicle-specific (unique) columns, e.g. ‘cert_co2e_grams_per_mile’ -> ‘veh_0_cert_co2e_grams_per_mile’. Used to track the data associated with individual Vehicles in a CompositeVehicle cost curve.
- Parameters:
vehicle (Vehicle) – the vehicle associated with the new column names
cost_curve (DataFrame) – the cost curve to rename columns in
- Returns:
cost_curve
with renamed columns
- class VehicleOnroadCalculations
Bases:
OMEGABase
Performs vehicle attribute calculations, as outlined in the input file.
Currently used to calculate the on-road “gap” in GHG performance. See the input file format above for more information.
- onroad_drive_cycle_weight_year = None
- battery_sizing_drive_cycle_weight_year = None
- static init_vehicle_attribute_calculations_from_file(filename, clear_cache=False, verbose=False)
Initialize class data from input file.
- Parameters:
filename (str) – name of input file
clear_cache (bool) – if
True
then clearVehicleAttributeCalculations._cache
verbose (bool) – enable additional console and logfile output if
True
- Returns:
List of template/input errors, else empty list on success
- static perform_onroad_calculations(vehicle, cost_cloud=None)
Perform onroad calculations as specified by the input file. Calculations may be applied to the vehicle directly, or to values in the cost_cloud if provided.
- Parameters:
vehicle (Vehicle) – the vehicle to perform calculations on
cost_cloud (DataFrame) – optional dataframe to perform calculations on
- Returns:
Nothing, If
cost_cloud
is not provided then attribute calculations are performed on the vehicle object else they are performed on the cost cloud data
- class CompositeVehicle(vehicles_list, vehicle_id, calc_composite_cost_curve=True, weight_by='initial_registered_count')
Bases:
OMEGABase
Implements vehicle composition and decomposition.
A CompositeVehicle contains a list of Vehicle objects whose attributes are weighted and combined to create “composite” attributes. The weighting may be by sales (initial registered count), for example. The sum of the weights do not need to add up to 1.0 or any other particular value within the group of Vehicles, they are normalized internally by the class, so ultimately the relative weights are what determine the composite attributes.
Of particular importance is the composite cost curve since it determines the range of technologies available to the manufacturer and their costs. The producer compliance search is on the basis of composite vehicles in order to reduce the mathematical complexity of the factorial search process.
During decomposition, the composite attributes are used to determine the attributes of the source Vehicles by reversing the weighting process. Vehicles must be grouped in such a way that the weighting values do not change within a simulation year or else the composition and decomposition process will be invalid since the weights must remain the same throughout the process.
Composite, normalized, target and cert CO2e Mg attributes are calculated from the bottom up based on the source Vehicle reg classes, physical attributes, etc, and the active policy.
- __init__(vehicles_list, vehicle_id, calc_composite_cost_curve=True, weight_by='initial_registered_count')
Create composite vehicle from list of Vehicle objects.
- Parameters:
([Vehicle (vehicles_list) – list of one or more
Vehicle
objects...] – list of one or more
Vehicle
objectsvehicle_id (str) – the vehicle id
calc_composite_cost_curve (bool) – if
True
then calculate the composite cost curveweight_by (str) – name of the
Vehicle
attribute to weight by, e.g. ‘initial_registered_count’ or'base_year_market_share' –
- retail_fuel_price_dollars_per_unit(calendar_year=None)
Calculate the weighted retail fuel price in dollars per unit from the Vehicles in the
vehicle_list
.- Parameters:
calendar_year (int) – the year to perform calculations in
- Returns:
Weighted Vehicle
retail_fuel_price_dollars_per_unit
- decompose()
Decompose composite vehicle attributes to source Vehicles in the
vehicle_list
. In addition to assigning Vehicle initial registered counts, attributes stored in the weighted cost curve are interpolated on the basis of compositecert_co2e_grams_per_mile
and assigned the Vehicles.- Returns:
Nothing, updates attributes of Vehicles in the
vehicle_list
See also
producer.vehicles.DecompositionAttributes
- calc_composite_cost_curve(plot=False)
Calculate a composite
cost_curve
from the cost curves of Vehicles in thevehicle_list
.Each Vehicle’s cost curve is sequentially weighted into the composite cost curve by performing a full factorial combination of the points in the prior composite curve with the new Vehicle’s curve and then calculating a new frontier from the resulting cloud. In this way the mathematical complexity of calculating the full factorial combination of all Vehicle cost curve points is avoided, while still arriving at the correct weighted answer for the frontier.
- Parameters:
plot (bool) – plot composite curve if
True
- Returns:
DataFrame containing the composite cost curve
- get_from_cost_curve(attribute_name, query_points)
Get new vehicle manufacturer cost from the composite cost curve for the provided cert CO2e g/mi value(s).
- Parameters:
attribute_name (str) – the name of the attribute to query
query_points (numeric list or Array) – the values at which to query the cost curve
- Returns:
A float or numeric Array of new vehicle manufacturer costs
- get_max_cost_curve_index()
Get maximum value from the cost curve interpolation axis, see
vehicles.cost_curve_interp_key
.- Returns:
A float, max value from the cost curve interpolation axis
- get_min_cost_curve_index()
Get minimum value from the cost curve interpolation axis, see
vehicles.cost_curve_interp_key
.- Returns:
A float, min value from the cost curve interpolation axis
- get_weighted_attribute(attribute_name)
Calculate the weighted value of the given attribute.
- Parameters:
attribute_name (str) – the name of the attribute to weight
- Returns:
The weighted value of the given attribute.
- calc_vehicle_frontier(vehicle)
Calculate the cost cloud and the frontier of the cost cloud for the given vehilce.
- Parameters:
vehicle (Vehicle) – the vehicle to calculate a frontier for
- Returns:
Returns
vehicle
with updated frontier
- is_up_for_redesign(vehicle)
Return
True
if vehicle is available for production and/or redesign
- update_dynamic_attributes(vehicle)
Update vehicle dynamic attributes
- Parameters:
vehicle (Vehicle) – the source vehicle
- Returns:
Nothing, updates vehicle dynamic attributes
See Also
transfer_vehicle_data()
- transfer_vehicle_data(from_vehicle, model_year)
Transfer data from a prior year Vehicle to a new Vehicle object. Updates reg class ID and target CO2e g/mi based on the model year and current policy.
- Parameters:
from_vehicle (Vehicle) – the source vehicle
model_year (int) – sets the
to_vehicle
model year
- Returns:
Returns new
Vehicle
object for the current model year
- class Vehicle(manufacturer_id)
Bases:
OMEGABase
Implements “candidate” or “working” vehicles for use during the producer compliance search.
Vehicle
objects are initialized fromVehicle
objects and then appropriate attributes are transferred fromVehicle
objects toVehicle
objects at the conclusion of the producer search and producer-consumer iteration.Each
Vehicle
object has a uniquecost_curve
(and potentiallycost_cloud
) that tracks multiple aspects of vehicle technology application as a function of cert CO2e g/mi and the data contained in the simulated vehicles file. The cost curve is calculated from the cost cloud at the start of each model year as a function of the active policy and the simulated vehicle data and costs. For example, the value of off-cycle credits may vary from one model year to the next and technology costs may decrease over time.See also
producer.vehicles.transfer_vehicle_data()
,Vehicle
,context.CostCloud
- compliance_ids = {}
the set of compliance IDs (manufacturer IDs or ‘consolidated_OEM’)
dict of base year market shares by compliance ID and various categories, used to project future vehicle sales based on the context
- mandatory_input_template_columns = {'application_id', 'battery_gross_kwh', 'body_style', 'cert_fuel_id', 'context_size_class', 'cost_curve_class', 'curbweight_lbs', 'drive_system', 'dual_rear_wheel', 'electrification_class', 'eng_rated_hp', 'footprint_ft2', 'gcwr_lbs', 'gvwr_lbs', 'in_use_fuel_id', 'manufacturer_id', 'model_year', 'msrp_dollars', 'prior_redesign_year', 'redesign_interval', 'reg_class_id', 'sales', 'structure_material', 'target_coef_a', 'target_coef_b', 'target_coef_c', 'total_emachine_kw', 'tractive_motor_kw', 'unibody_structure', 'vehicle_name'}
- dynamic_columns = []
additional data columns such as footprint, passenger capacity, etc
- dynamic_attributes = []
list of dynamic attribute names, from dynamic_columns
- __init__(manufacturer_id)
Create a new
Vehicle
object- Parameters:
manufacturer_id (str) – manufacturer id, e.g. ‘consolidated_OEM’, ‘Ford’, etc
- application_id
application ID ‘SLA’ -> standard load application, ‘HLA’ -> high load application
- battery_kwh
vehicle propulsion battery kWh
- battery_sizing_onroad_direct_kwh_per_mile
battery-sizing onroad direct kWh/mi
- body_style
vehicle body style, e.g. ‘sedan’
- cert_co2e_Mg
cert CO2e Mg, as determined by the active policy
- cert_engine_on_distance_frac
xHEV cert engine-on distance frac
- cert_fuel_id
cert fuel ID
- cert_utility_factor
PHEV cert utility factor (weighted average)
- compliance_id
compliance ID, may be the manufacturer ID or ‘consolidated_OEM’
- context_size_class
context size class, used to project future vehicle sales based on the context
- cost_curve
the vehicle cost curve (tech frontier)
- cost_curve_class
vehicle simulation (e.g. ALPHA) modeling result class
- curbweight_lbs
vehicle curbweight, pounds
- drive_system
drive system, ‘FWD’, ‘RWD’, ‘AWD’
- dual_rear_wheel
dual_rear_wheel, 0=No, 1=Yes
- footprint_ft2
vehicle footprint, square feet
- fueling_class
fueling class, e.g. ‘BEV’, ‘ICE’
- gcwr_lbs
gross combined weight rating, lbs
- gvwr_lbs
gross vehicle weight rating, lbs
- in_production
True
if vehicle is in production
- in_use_fuel_id
in-use / onroad fuel ID
- lifetime_VMT
lifetime VMT, used to calculate CO2e Mg
- manufacturer_id
vehicle manufacturer ID
- market_class_id
market class ID, as determined by the consumer subpackage
- market_class_cross_subsidy_multiplier
vehicle market class cross subsidy multiplier
- model_year
vehicle model year
- model_year_prevalence
used to maintain market share relationships within context size classes during market projection
- modified_cross_subsidized_price_dollars
vehicle modified cross subsidized price in dollars
- name
vehicle name
- onroad_engine_on_distance_frac
xHEV onroad engine-on disance frac
- onroad_charge_depleting_range_mi
on-road charge-depleting range, miles
- onroad_direct_oncycle_co2e_grams_per_mile
onroad direct oncycle CO2e g/mi
- onroad_direct_oncycle_kwh_per_mile
onroad direct oncycle kWh/mi
- onroad_utility_factor
PHEV onroad utility factor (weighted average)
- price_dollars
vehicle price in dollars
- price_modification_dollars
vehicle price modification (i.e. incentive value) in dollars
- prior_redesign_year
prior redesign year
- projected_sales
used to project context size class sales
- redesign_interval
redesign interval, years
- reg_class_id
regulatory class assigned according the active policy
- structure_material
vehicle body structure material, e.g. ‘steel’
- target_co2e_Mg
target CO2e Mg, as determined by the active policy
- target_co2e_grams_per_mile
cert target CO2e g/mi, as determined by the active policy
- total_emachine_kw
vehicle motor/generator total combined power, kW
- tractive_motor_kw
on-cycle tractive motor power, kW
- unibody_structure
unibody structure flag, e.g. 0,1
- vehicle_id
unique vehicle ID
- workfactor
medium-duty workfactor
- base_year_battery_kwh
vehicle propulsion battery kWh
- base_year_cert_direct_oncycle_co2e_grams_per_mile
base year cert direct oncycle CO2e g/mi
- base_year_cert_direct_oncycle_kwh_per_mile
base year cert direct oncycle kWh/mi
- base_year_cert_fuel_id
base year cert fuel ID
- base_year_cost_curve_class
base year cost curve class
- base_year_curbweight_lbs
base year vehicle curbweight, pounds
- base_year_curbweight_lbs_to_hp
base year curbweight to power ratio (pounds per hp)
- base_year_eng_rated_hp
base year engine rated horsepower
- base_year_footprint_ft2
base year vehicle footprint, square feet
- base_year_gcwr_lbs
base year gross combined weight rating, lbs
- base_year_glider_non_structure_mass_lbs
base year non-structure mass lbs (i.e. “content”)
- base_year_glider_non_structure_cost_dollars
base year glider non-structure cost dollars
- base_year_glider_structure_cost_dollars
base year glider structure cost dollars
- base_year_gvwr_lbs
base year gross vehicle weight rating, lbs
base year market share, used to maintain market share relationships within context size classes
- base_year_msrp_dollars
base year Manufacturer Suggested Retail Price (dollars)
- base_year_onroad_charge_depleting_range_mi
charge depleting range, miles
- base_year_onroad_direct_oncycle_co2e_grams_per_mile
base year onroad direct oncycle CO2e g/mi
- base_year_onroad_direct_oncycle_kwh_per_mile
base year onroad direct oncycle kWh/mi
- base_year_powertrain_type
vehicle powertrain type, e.g. ‘ICE’, ‘HEV’, etc
- base_year_product
1
if vehicle was in production in base year, else0
- base_year_reg_class_id
base year regulatory class, historical data
- base_year_target_coef_a
roadload A coefficient, lbs
- base_year_target_coef_b
roadload B coefficient, lbs/mph
- base_year_target_coef_c
roadload C coefficient, lbs/mph^2
- base_year_total_emachine_kw
vehicle motor/generator total combined power, kW
- base_year_tractive_motor_kw
on-cycle tractive motor power, kW
- base_year_vehicle_id
base year vehicle id from vehicles.csv
- base_year_workfactor
base year medium-duty workfactor
- static reset_vehicle_ids()
Reset vehicle IDs. Sets
Vehicle.next_vehicle_id
to an initial value.
- static get_next_vehicle_id(manufacturer_id)
Gets vehicle id and increments
Vehicle.next_vehicle_id
.- Parameters:
manufacturer_id (str) – manufacturer id, e.g. ‘consolidated_OEM’, ‘Ford’, etc
- property initial_registered_count
Get the vehicle initial registered count
- Returns:
The vehicle initial registered count
- retail_fuel_price_dollars_per_unit(calendar_year=None)
Get the retail fuel price for the Vehicle in dollars per unit for the given calendar year. Used to calculate producer generalized cost and also average fuel cost by market class.
- Parameters:
calendar_year (int) – the year to get the price in
- Returns:
The retail fuel price in dollars per unit for the given year.
- onroad_co2e_emissions_grams_per_unit()
Calculate the onroad (in-use) CO2e emission in grams per unit of onroad fuel, including refuel efficiency. Used to calculate producer generalized cost.
- Returns:
The onroad CO2e emission in grams per unit of onroad fuel, including refuel efficiency.
- set_target_co2e_grams_per_mile()
Set the vehicle cert target CO2e grams per mile based on the current policy and vehicle attributes.
- Returns:
Nothing, updates
target_co2e_grams_per_mile
- set_target_co2e_Mg()
Set the vehicle cert target CO2e megagrams based on the current policy and vehicle attributes.
- Returns:
Nothing, updates
target_co2e_Mg
- set_cert_co2e_Mg()
Set the vehicle cert CO2e megagrams based on the current policy and vehicle attributes.
- Returns:
Nothing, updates
cert_co2e_Mg
- calc_battery_sizing_onroad_direct_kWh_per_mile(cloud)
Calculate the battery-sizing onroad direct vehicle kWh/mi
- Parameters:
cloud (DataFrame) – vehicle cost cloud
- Returns:
cloud
with updated values
- calc_cert_and_onroad_values(cloud)
Calculate cert and onroad CO2e g/mi, kWh/mi engine-on distance frac and other values.
- Parameters:
cloud (DataFrame) – vehicle cost cloud
- Returns:
cloud
with updated values
- calc_cost_curve(cost_cloud)
Create a frontier (“cost curve”) from a vehicle’s cloud of simulated vehicle points (“cost cloud”) based on the current policy and vehicle attributes. The cost values are a function of the producer generalized cost and the CO2e values are a function of the simulated vehicle data and the policy.
Policy factors that modify the cost cloud and may modify the frontier from year to year include off cycle credit values, drive cycle weightings, upstream values, etc. This method is also where costs could be updated dynamically before calculating the frontier (for example, cost reductions due to learning may already be present in the cost cloud, or could be implemented here instead).
Additionally, each point in the frontier contains the values as determined by
DecompositionAttributes
.- Parameters:
cost_cloud (DataFrame) – vehicle cost cloud
- Returns:
None, updates vehicle.cost_curve with vehicle tecnhology frontier / cost curve as a DataFrame.
- static assign_vehicle_market_class_ID(vehicle)
Assign market class ID to the given vehicle and update manufacturer market class data.
- Parameters:
vehicle (Vehicle) – the vehicle to assign a market class ID to
- Returns:
Nothing, updates vehicle market class ID and manufacturer market class data
- static set_fueling_class(vehicle)
Set vehicle fueling class.
- Parameters:
vehicle (Vehicle) – the vehicle to assign a fueling class to
- Returns:
Nothing, updates the vehicle’s fueling_class attribute
- property fueling_class_reg_class_id
Create string combining fueling class id and regulatory class id.
- Returns:
String combining fueling class id and regulatory class id, e.g. ‘ICE.car’
- static create_vehicle_clone(vehicle)
Create vehicle clone.
- Parameters:
vehicle (Vehicle) – the vehicle to clone
- Returns:
Cloned vehicle
- static clone_vehicle(vehicle)
Make a “clone” of a vehicle, used to create alternate powertrain versions of vehicles in the base year fleet
- Parameters:
vehicle (Vehicle) – the vehicle to clone
- Returns:
A new
Vehicle
object with non-powertrain attributes copied from the given vehicle
- static init_vehicles_from_dataframe(df, verbose=False)
Load data from the base year vehicle dataframe
- Parameters:
df (DataFrame) – dataframe of aggregated vehicle data
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
- static init_from_file(vehicle_onroad_calculations_file, verbose=False)
Init vehicle data from the base year vehicles file and set up the onroad / vehicle attribute calculations. Also initializes decomposition attributes.
- Parameters:
vehicle_onroad_calculations_file (str) – the name of the vehicle onroad calculations (vehicle attribute calculations) file
verbose (bool) – enable additional console and logfile output if True
- Returns:
List of template/input errors, else empty list on success
See also
VehicleAttributeCalculations
,DecompositionAttributes
7.3.2. Submodules
7.3.3. omega_model.omega module
OMEGA top level code
Runs a single session, writes info to log files and the console, executes session post-processing.
CODE
- calc_cross_subsidy_options_and_response(calendar_year, market_class_tree, compliance_id, producer_decision, cross_subsidy_options_and_response, producer_consumer_iteration_num, iteration_log, node_name='', verbose=False)
Traverse the market class tree and generate cross subsidy multipliers and the associated consumer response for responsive market categories/classes
- Parameters:
calendar_year (int) – the year in which the compliance calculations take place
market_class_tree (dict) – a dict of CompositeVehicle object lists hiearchically grouped by market categories into market classes
compliance_id (str) – name of manufacturer, e.g. ‘consolidated_OEM’
producer_decision (Series) – result of producer compliance search, without consumer response
cross_subsidy_options_and_response (DataFrame, Series) – initiall empty dataframe or Series containing cross subsidy options and response
producer_consumer_iteration_num (int) – producer-consumer iteration number
iteration_log (DataFrame) – DataFrame of producer-consumer iteration data
node_name (str) – name of the current node
verbose (bool) – enable additional console output if True
- Returns:
tuple of
cross_subsidy_options_and_response
, updatediteration_log
Write detailed producer-consumer cross-subsidy iteration data to the log and console. For investigation of cross-subsidy search behavior. Optionally called from
iterate_producer_cross_subsidy()
- Parameters:
calendar_year (int) – calendar year of the data
producer_market_classes (list) – list of producer market classes, e.g. [‘hauling.ICE’, ‘hauling.BEV’, …]
share_convergence_error (float) – producer-consumer convergence error
cross_subsidy_pricing_error (float) – cross-subsidy pricing error
producer_decision_and_response (Series) – producer compliance search result with consumer share response
producer_consumer_iteration_num (int) – producer-consumer iteration number
cross_subsidy_iteration_num (int) – cross-subsidy iteration number
Example
2020 producer / consumer_abs_share_frac_cuv_suv_van.BEV = 0.001934 / 0.004204 (DELTA:0.002269) 2020 producer / consumer_abs_share_frac_cuv_suv_van.ICE = 0.560920 / 0.558651 (DELTA:0.002269) 2020 producer / consumer_abs_share_frac_pickup.BEV = 0.000000 / 0.001080 (DELTA:0.001080) 2020 producer / consumer_abs_share_frac_pickup.ICE = 0.141411 / 0.140331 (DELTA:0.001080) 2020 producer / consumer_abs_share_frac_sedan_wagon.BEV = 0.009009 / 0.009009 (DELTA:0.000000) 2020 producer / consumer_abs_share_frac_sedan_wagon.ICE = 0.286726 / 0.286726 (DELTA:0.000000) cross subsidized price / cost ALT cuv_suv_van.BEV $59676 / $54251 R:1.100000 cross subsidized price / cost ALT cuv_suv_van.ICE $34655 / $34696 R:0.998822 cross subsidized price / cost ALT pickup.BEV $69475 / $63159 R:1.100000 cross subsidized price / cost ALT pickup.ICE $40640 / $40689 R:0.998805 cross subsidized price / cost ALT sedan_wagon.BEV $46913 / $46913 R:1.000000 cross subsidized price / cost ALT sedan_wagon.ICE $30698 / $30698 R:1.000000 modified cross subsidized price / cost ALT cuv_suv_van.BEV $59676 / $54251 R:1.100000 modified cross subsidized price / cost ALT cuv_suv_van.ICE $34655 / $34696 R:0.998822 modified cross subsidized price / cost ALT pickup.BEV $69475 / $63159 R:1.100000 modified cross subsidized price / cost ALT pickup.ICE $40640 / $40689 R:0.998805 modified cross subsidized price / cost ALT sedan_wagon.BEV $46913 / $46913 R:1.000000 modified cross subsidized price / cost ALT sedan_wagon.ICE $30698 / $30698 R:1.000000 cross subsidized price / cost ALT BEV $52371 / $50299 R:1.041208 cross subsidized price / cost ALT ICE $34356 / $34386 R:0.999125 cross subsidized price / cost ALT cuv_suv_van $34842 / $34842 R:0.999999 cross subsidized price / cost ALT pickup $40861 / $40861 R:0.999999 cross subsidized price / cost ALT sedan_wagon $31192 / $31192 R:1.000000 cross subsidized price / cost ALT TOTAL $34613 / $34613 R:0.999999 2020_0_0 SCORE:0.000296, CE:0.002269, CSPE:0.000001
- update_cross_subsidy_log_data(producer_decision_and_response, calendar_year, compliance_id, converged, producer_consumer_iteration_num, compliant, share_convergence_error)
Adds/updates data in the producer decision and response for the given arguments.
- Parameters:
producer_decision_and_response (Series) – producer decision and cross-subsidy iteration response data
calendar_year (int) – calendar year of the data
compliance_id (str) – manufacturer name, or ‘consolidated_OEM’
converged (bool) –
True
if producer and consumer market shares are within toleranceproducer_consumer_iteration_num (int) – producer-consumer iteration number
compliant (bool or None) –
True
if producer was able to find a compliant production optionshare_convergence_error (float) – producer-consumer convergence error
- run_compliance_id(compliance_id, pass_num, cumulative_battery_GWh, credit_banks, manufacturer_annual_data_table, iteration_log)
- run_producer_consumer(pass_num, manufacturer_annual_data_table)
Create producer cost-minimizing technology and market share options, in consideration of market response from the consumer, possibly with iteration between the two. Iterates across years for each compliance ID. When consolidating manufacturers, the compliance ID is ‘consolidated_OEM’, otherwise the compliance ID is the manufacturer name.
- Parameters:
pass_num (int) – the pass number, 0 = first, 1 = second, etc.
manufacturer_annual_data_table (None, or DataFrame) – if provided, contains manufacturer-level data from the
pass (first) –
- Returns:
Iteration log dataframe, dict of credit bank information (iteration_log, credit_banks), updates omega data with final vehicle technology and market share data
- calc_cross_subsidy_metrics(mcat, cross_subsidy_group, producer_decision, cross_subsidy_options_and_response)
Calculate cross-subsidy metrics (prices and share deltas).
- Parameters:
mcat (str) – market category, e.g. ‘hauling’ / ‘non_hauling’
cross_subsidy_group (list) – list of cross-subsidized market classes, e.g. [‘hauling.BEV’, ‘hauling.ICE’]
producer_decision (Series) – result of producer compliance search, without consumer response
cross_subsidy_options_and_response (DataFrame) – dataframe containing cross subsidy options and response
- Returns:
Nothing, updates
cross_subsidy_options_and_response
- iterate_producer_cross_subsidy(calendar_year, compliance_id, best_producer_decision_and_response, candidate_mfr_composite_vehicles, iteration_log, producer_consumer_iteration_num, producer_market_classes, producer_decision, strategic_target_offset_Mg)
Perform producer pricing cross-subsidy iteration. Cross-subsidy maintains the total average price, as well as average price by non-responsive market categories. The goal is to achieve convergence between producer and consumer desired absolute market class shares, within a tolerance. The cross-subsidy is implemented through price multipliers, the minimum and maximum range of which are user inputs (e.g. 0.95 -> 1.05). The initial range of multipliers is the full span from min to max, subsequent iterations tighten the range and hone in on the multipliers that provide the most convergent result while maintaining the average prices mentioned above.
- Parameters:
calendar_year (int) – calendar year of the iteration
compliance_id (str) – manufacturer name, or ‘consolidated_OEM’
best_producer_decision_and_response (Series) – producer compliance search result with consumer share response with best convergence
candidate_mfr_composite_vehicles ([CompositeVehicles]) – list of manufacturer composite vehicles, production candidates
iteration_log (DataFrame) – DataFrame of producer-consumer and cross-subsidy iteration data
producer_consumer_iteration_num (int) – producer-consumer iteration number
producer_market_classes (list) – list of candidate_mfr_composite_vehicles grouped by market class
producer_decision (Series) – result of producer compliance search, without consumer response
strategic_target_offset_Mg (float) – desired producer distance from compliance, in CO2e Mg, zero for compliance, > 0 for under-compliance, < 0 for over-compliance
- Returns:
tuple of best producer decision and response, the iteration log, and last producer decision and response (best_producer_decision_and_response, iteration_log, cross_subsidy_options_and_response)
- logwrite_cross_subsidy_results(calendar_year, producer_market_classes, cross_subsidy_pricing_error, producer_consumer_iteration_num, producer_decision_and_response, share_convergence_error)
Write cross-subsidy data to the console / session log
- Parameters:
calendar_year (int) – calendar year of the iteration
producer_market_classes (list) – list of producer market classes, e.g. [‘hauling.ICE’, ‘hauling.BEV’, …]
cross_subsidy_pricing_error (float) – the cross subsidy pricing error
producer_consumer_iteration_num (int) – producer-consumer iteration number
producer_decision_and_response (Series) – producer decision and cross-subsidy iteration response data
share_convergence_error (float) – producer-consumer share convergence error
- Returns:
Nothing, updates console log and
omega_globals.price_modification_data
- search_cross_subsidies(calendar_year, compliance_id, mcat, cross_subsidy_group, producer_decision, cross_subsidy_options_and_response, producer_consumer_iteration_num, iteration_log)
Search the available cross-subsidy space (as determined by min and max pricing multipliers) for multipliers that minimize the error between producer and consumer market shares while maintaining revenue neutrality for the producer.
- Parameters:
calendar_year (int) – the year in which the compliance calculations take place
compliance_id (str) – name of manufacturer, e.g. ‘consolidated_OEM’
mcat (str) – market category, e.g. ‘hauling’ / ‘non_hauling’
cross_subsidy_group (list) – list of cross-subsidized market classes, e.g. [‘hauling.BEV’, ‘hauling.ICE’]
producer_decision (Series) – result of producer compliance search, without consumer response
cross_subsidy_options_and_response (DataFrame, Series) – initially empty dataframe or Series containing cross subsidy options and response
producer_consumer_iteration_num (int) – producer-consumer iteration number
iteration_log (DataFrame) – DataFrame of producer-consumer iteration data
- Returns:
tuple of
cross_subsidy_options_and_response
, updatediteration_log
- update_cross_subsidy_group_console_log(cross_subsidy_group, share_convergence_error, cross_subsidy_pricing_error, mcat_converged)
Write producer-consumer cross subsidy data to the console and log, if enabled by
verbose_console_modules
.- Parameters:
cross_subsidy_group (list) – e.g. [‘hauling.ICE’, ‘hauling.BEV’]
share_convergence_error (float) – producer-consumer convergence error
cross_subsidy_pricing_error (float) – cross-subsidy pricing error
mcat_converged (bool) –
True
if the market class price/cost ratioand the producer-consumer shares are within tolerance
Calculate sales and cost/price data. Namely, the absolute share delta between producer and consumer absolute market shares, the share weighted average cross subsidized price by market class, the total share weighted average cross subsidized price, the average modified cross subsidized price by market class, the average new vehicle manufacturer cost and generalized cost, and total new vehicle sales, including the market response to average new vehicle manufacturer generalized cost.
- Parameters:
calendar_year (int) – calendar year of the iteration
compliance_id (str) – manufacturer name, or ‘consolidated_OEM’
producer_market_classes (list) – list of producer market classes
producer_decision_and_response (Series) – producer compliance search result with consumer share response
- Returns:
Updates
producer_decision_and_response
columns
- create_cross_subsidy_options(calendar_year, continue_search, mc_pair, multiplier_columns, prev_multiplier_range, producer_decision, producer_decision_and_response)
Calculate cross subsidy pricing options based on the allowable multiplier range, within a subsequently smaller range as iteration progresses, until the search collapses (min multiplier == max multiplier).
- Parameters:
calendar_year (int) – calendar year of the iteration
continue_search (bool) – prior value of
continue_search
, set toFalse
if search collapsesmc_pair ([strs]) –
multiplier_columns ([strs]) – list of cost multiplier columns, e.g. [‘cost_multiplier_hauling.BEV’, ‘cost_multiplier_hauling.ICE’, …]
prev_multiplier_range (dict) – empty on first pass then contains a dict of previous multiplier ranges by market class, e.g. {‘cost_multiplier_hauling.BEV’: array([0.95, 0.98333333, 1.0, 1.01666667, 1.05]), …}
producer_decision (DataFrame) – producer production decision dataframe
producer_decision_and_response (DataFrame, Series) – empty DataFrame on first pass then contains producer compliance search result and most-convergent consumer response to previous cross subsidy options as a Series
- Returns:
tuple of whether to continue cross subsidy search, dataframe of producer decision with cross subsidy pricing options (continue_search, price_options_df)
- tighten_multiplier_range(multiplier_column, prev_multiplier_ranges, producer_decision_and_response, search_collapsed)
Tighten cross subsidy multiplier range.
- Parameters:
multiplier_column (str) – name of the multiplier range to tighten, e.g. ‘cost_multiplier_hauling.BEV’
prev_multiplier_ranges (dict) – empty on first pass then contains a dict of previous multiplier ranges by market class, e.g. {‘cost_multiplier_hauling.BEV’: array([0.95, 0.98333333, 1.0, 1.01666667, 1.05]), …}
producer_decision_and_response (Series) – contains producer compliance search result and most-convergent consumer response to previous cross subsidy options
search_collapsed (bool) – prior value of search collapsed, gets ANDed with collapse condition
- Returns:
tuple of multiplier range array (e.g. array([1.01666667, 1.02777778, 1.03888889, 1.05])) and whether search has collapsed (multiplier_range, search_collapsed)
- calc_market_class_data_from_composite_vehicles(candidate_mfr_composite_vehicles, producer_decision)
Creates a dictionary of candidate vehicles binned by market class, calculates market class and market category data via
calc_market_class_data()
andcalc_market_category_data()
- Parameters:
candidate_mfr_composite_vehicles (list) – list of candidate composite vehicles that minimize producer compliance cost
producer_decision (Series) – Series that corresponds with candidate_mfr_composite_vehicles, has producer market shares, costs, compliance data (Mg CO2e), may also contain consumer response
- Returns:
list of producer market classes (market classes with candidate vehicles), updates producer_decision with calculated market data
See also
calc_market_class_data()
,calc_market_category_data()
- calc_market_class_data_from_market_class_vehicles(market_class_vehicle_dict, producer_decision)
Calculate market class average CO2e g/mi, kWh/mi, manufacturer new vehicle cost and generalized cost, average fuel price, and other sales-weighted vehicle attributes such as footprint, curbweight, etc.
- Parameters:
market_class_vehicle_dict (dict) – candidate vehicles binned by market class
producer_decision (Series) – Series that corresponds with candidate_mfr_composite_vehicles, has producer market shares, costs, compliance data (Mg CO2e), may also contain consumer response
- Returns:
Nothing, updates
producer_decsion
with calculated market data
- calc_market_data_from_sales(candidate_mfr_composite_vehicles, producer_decision)
Calculates market class and market category data via
calc_market_class_sales_from_producer_decision()
andcalc_market_category_data_from_sales()
- Parameters:
candidate_mfr_composite_vehicles (list) – list of candidate composite vehicles that minimize producer compliance cost
producer_decision (Series) – Series that corresponds with candidate_mfr_composite_vehicles, has producer market shares, costs, compliance data (Mg CO2e), may also contain consumer response
- Returns:
updates producer_decision with calculated market data
See also
calc_market_class_data()
,calc_market_category_data()
- calc_market_class_sales_from_producer_decision(market_class_vehicle_dict, producer_decision)
Calculate market class sales from
producer_decision
composite vehicle sales.- Parameters:
market_class_vehicle_dict (dict) – candidate vehicles binned by market class
producer_decision (Series) – Series that corresponds with candidate_mfr_composite_vehicles, has producer market shares, costs, compliance data (Mg CO2e), may also contain consumer response
- Returns:
Nothing, updates market class values in
producer_decision
- calc_market_category_data_from_sales(producer_decision)
Calculate market category average cost and generalized cost, average cross subsidized price, sales, producer absolute shares and other sales-weighted market class attributes such as footprint, curbweight, etc.
- Parameters:
producer_decision (Series) – Series that corresponds with candidate_mfr_composite_vehicles, has producer market shares, costs, compliance data (Mg CO2e), may also contain consumer response
- Returns:
Nothing, updates
producer_decsion
with calculated market category data
- detect_producer_consumer_convergence(producer_decision_and_response, producer_market_classes)
Detect producer-consumer market share convergence.
- Parameters:
producer_decision_and_response (Series) – contains producer compliance search result and most-convergent consumer response to previous cross subsidy options
producer_market_classes (list) – list of producer market classes
- Returns:
tuple of convergence bool and share convergence error and cross subsidy pricing error
- get_module(module_name)
Get a Python module by module name
- Parameters:
module_name (str) – e.g. ‘consumer.market_classes’
- Returns:
The module specified by the module name
- import_user_definable_submodules()
Import dynamic modules that are specified by the input file input template name and set the session runtime options appropriately.
- Returns:
List of template/input errors, else empty list on success
- init_user_definable_decomposition_attributes(verbose_init)
Init user definable decomposition attributes. Decomposition attributes are values that are tracked at each point in a vehicle’s cost curve / frontier during composition and are interpolated during decomposition. Examples of decomposition attributes are individual drive cycle results and off-cycle credit values. Technology application can also be tracked via optional flags in the simulated vehicles (cost cloud) data.
- Parameters:
verbose_init (bool) – if
True
enable additional init output to console- Returns:
List of template/input errors, else empty list on success
See also
producer.vehicles.DecompositionAttributes
,producer.vehicles.Vehicle
- init_omega(session_runtime_options)
Initialize OMEGA data structures.
- Parameters:
session_runtime_options (OMEGASessionSettings) – session runtime options
- Returns:
List of template/input errors, else empty list on success
- poolstart()
Placeholder for pool startup function
- Returns:
None
- error_callback(e)
Print multiprocess error callback to the console.
- Parameters:
e (BaseException) – exception info
- run_omega(session_runtime_options, standalone_run=False)
Run a single OMEGA simulation session and run session postproc.
- Parameters:
session_runtime_options (OMEGASessionSettings) – session runtime options
standalone_run (bool) – True if session is run outside of the batch process
7.3.4. omega_model.omega_batch module
Routines to load and run a batch of one or more OMEGA simulation sessions.
Sessions are defined by columns of data, some rows support multiple comma-separated values, which are expanded in a full-factorial fashion. All required session data, including source code, is “bundled” to a common folder, thereby providing a standalone archive of the batch that can be inspected or re-run at any time.
The batch process supports parallel processing via multi-core and/or multi-machine running of batches via the optional
dispy
package. Parallel processing requires the machine(s) to have running instances of dispynode
s and
optionally a dispyscheduler
. Parallel processing is an advanced topic and is not covered in detail here.
Example command-line shell script for launching a dispy node:
#! /bin/zsh PYTHONPATH="/Users/omega_user/Code/GitHub/USEPA_OMEGA2/venv3.8/bin" DISPYPATH="/Users/omega_user/Code/GitHub/USEPA_OMEGA2/venv3.8/lib/python3.8/site-packages/dispy" $PYTHONPATH/python3 $DISPYPATH/dispynode.py --clean --cpus=8 --client_shutdown --ping_interval=15 --daemon --zombie_interval=5
INPUT FILE FORMAT
The file format consists of a two-column header followed by a one or more session definition columns. Batch settings (settings that apply to all sessions) are defined in the first column (at the top, by convention). The data rows do not need to be defined in any particular order.
- Sample Data Columns
Parameter
Type
Value
Batch Settings
Batch Name
String
test_batch
Analysis Final Year
#
2024
Analysis Dollar Basis
#
2022
Batch Analysis Context Settings
Context Name
String
AEO2023
Context Case
String
Reference case
Credit Market Efficiency
#
1
Context Fuel Prices File
String
context_fuel_prices.csv
Context Electricity Prices File
String
context_electricity_prices_aeo.csv
Context New Vehicle Market File
String
context_new_vehicle_market-body_style.csv
Manufacturers File
String
manufacturers.csv
Market Classes File
String
market_classes_ice_bev_phev-body_style.csv
New Vehicle Price Elasticity of Demand
#
-0.4
Onroad Fuels File
String
onroad_fuels.csv
Onroad Vehicle Calculations File
String
onroad_vehicle_calculations.csv
Onroad VMT File
String
annual_vmt_fixed_by_age_ice_bev_phev-body_style.csv
Producer Cross Subsidy Multiplier Max
#
1.1
Producer Cross Subsidy Multiplier Min
#
0.9
Producer Generalized Cost File
String
producer_generalized_cost-body_style.csv
Production Constraints File
String
production_constraints-body_style.csv
Sales Share File
String
sales_share_params_ice_bev_phev_body_style.csv
Vehicle Price Modifications File
String
vehicle_price_modifications-body_style.csv
Vehicle Reregistration File
String
reregistration_fixed_by_age_ice_bev_phev-body_style.csv
ICE Vehicle Simulation Results File
String
simulated_vehicles_rse_ice.csv
BEV Vehicle Simulation Results File
String
simulated_vehicles_rse_bev.csv
PHEV Vehicle Simulation Results File
String
simulated_vehicles_rse_phev.csv
Vehicles File
String
vehicles.csv
Powertrain Cost File
String
powertrain_cost.csv
Glider Cost File
String
glider_cost.csv
Body Styles File
String
body_styles.csv
Mass Scaling File
String
mass_scaling.csv
Workfactor Definition File
String
workfactor_definition.csv
Session Settings
Enable Session
TRUE / FALSE
TRUE
TRUE
Session Name
String
NoActionPolicy
ActionAlternative
Session Policy Alternatives Settings
Drive Cycle Weights File
String
drive_cycle_weights.csv
drive_cycle_weights.csv
Drive Cycle Ballast File
String
drive_cycle_ballast.csv
drive_cycle_ballast.csv
Drive Cycles File
String
drive_cycles.csv
drive_cycles.csv
GHG Credit Params File
String
ghg_credit_params.csv
ghg_credit_params.csv
GHG Credits File
String
ghg_credits.csv
ghg_credits.csv
GHG Standards File
String
ghg_standards-footprint.csv
ghg_standards-0.csv
Off-Cycle Credits File
String
offcycle_credits.csv
offcycle_credits.csv
Policy Fuel Upstream Methods File
String
policy_fuel_upstream_methods.csv
policy_fuel_upstream_methods.csv
Policy Fuels File
String
policy_fuels.csv
policy_fuels.csv
Production Multipliers File
String
production_multipliers.csv
production_multipliers.csv
Regulatory Classes File
String
regulatory_classes.csv
regulatory_classes.csv
Required Sales Share File
String
required_sales_share-body_style.csv
required_sales_share-body_style.csv
Policy Utility Factor Methods File
String
policy_utility_factor_methods.csv
policy_utility_factor_methods.csv
Context Implicit Price Deflators File
String
implicit_price_deflators.csv
implicit_price_deflators.csv
The first column defines the parameter name, the second column is a type-hint and does not get evaluated. Subsequent columns contain the data to define batch settings and session settings.
File names in the batch definition file are relative to the batch file location, unless they are specified as absolute paths.
Data Row Name and Description
- Batch Settings:
Decorator, not evaluated
- Batch Name (str):
The name of the batch, combined with a timestamp (YYYY_MM_DD_hh_mm_ss) becomes the name of the bundle folder
- Analysis Final Year (int):
Analysis Final Year, e.g.
2050
- Analysis Dollar Basis:
The dollar valuation for all monetized values in the cost effects outputs, i.e., costs are expressed in “Dollar Basis” dollars
- Batch Analysis Context Settings:
Decorator, not evaluated
- Context Name (str):
Context name, e.g.
AEO2021
- Context Case (str):
Context case name, e.g.
Reference case
- Credit Market Efficiency (float):
The “credit market efficiency”, [0..1]. 1 = perfect ghg credit trading, 0 = no ghg credit trading
- Context Fuel Prices File (str):
The relative or absolute path to the context fuel prices file, loaded by
context.fuel_prices.FuelPrice
- Context Electricity Prices File (str)):
The relative or absolute path to the context electricity prices file, loaded by user-definable
ElectricityPrices
class defined in the module specified by the file header, e.g.context.electricity_prices_aeo
- Context New Vehicle Market File (str):
The relative or absolute path to the context new vehicle market file, loaded by
context.new_vehicle_market.NewVehicleMarket
- Manufacturers File (str):
The relative or absolute path to the manufacturers file, loaded by
producer.manufacturers.Manufacturer
- Market Classes File (str):
The relative or absolute path to the market classes file, loaded by user-definable
MarketClass
class defined in the module specified by the file header, e.g.consumer.market_classes_ice_bev_body_style
- New Vehicle Price Elasticity of Demand (float, …):
Numeric value of the new vehicle price elasticity of demand, typically <= 0, e.g.
-0.5
Supports multiple comma-separated values- Onroad Fuels File (str):
The relative or absolute path to the onroad fuels file, loaded by
context.onroad_fuels.OnroadFuel
- Onroad Vehicle Calculations File (str):
The relative or absolute path to the onroad vehicle calculations (onroad gap) file, loaded by
producer.vehicles.Vehicle
- Onroad VMT File (str):
The relative or absolute path to the onroad VMT file, loaded dynamically by the
OnroadVMT
class defined in the module specified by the file header, e.g.consumer.annual_vmt_fixed_by_age
- Producer Cross Subsidy Multiplier Max (float, …):
Numeric value of the minimum producer cross subsidy multiplier, typically >= 1, e.g.
1.05
Supports multiple comma-separated values- Producer Cross Subsidy Multiplier Min (float, …):
Numeric value of the minimum producer cross subsidy multiplier, typically <= 1, e.g.
0.95
Supports multiple comma-separated values- Producer Generalized Cost File (str):
The relative or absolute path to the vehicle producer generalized costs file, loaded dynamically by the
ProducerGeneralizedCost
class defined in the module specified by the file header, e.g.producer.producer_generalized_cost
- Production Constraints File (str):
The relative or absolute path to the production constraints file, loaded by
context.production_constraints.ProductionConstraints
- Sales Share File (str):
The relative or absolute path to the sales share (consumer sales response) file, loaded dynamically by the
SalesShare
class defined in the module specified by the file header, e.g.consumer.sales_share_ice_bev_phev_body_style
- Vehicle Price Modifications File (str):
The relative or absolute path to the vehicle price modifications file, loaded by
context.price_modifications.PriceModifications
- Vehicle Reregistration File (str):
The relative or absolute path to the vehicle re-registration file, loaded dynamically by the
Reregistration
class defined in the module specified by the file header, e.g.consumer.reregistration_fixed_by_age
- ICE Vehicle Simulation Results File (str):
The relative or absolute path to the ICE vehicle simulation results file, loaded by user-definable
CostCloud
class defined in the module specified by the file header, e.g.context.rse_cost_clouds
- BEV Vehicle Simulation Results File (str):
The relative or absolute path to the BEV vehicle simulation results file, loaded by user-definable
CostCloud
class defined in the module specified by the file header, e.g.context.rse_cost_clouds
- PHEV Vehicle Simulation Results File (str):
The relative or absolute path to the PHEV vehicle simulation results file, loaded by user-definable
CostCloud
class defined in the module specified by the file header, e.g.context.rse_cost_clouds
- Vehicles File (str):
The relative or absolute path to the vehicles (base year fleet) file, loaded by
producer.vehicle_aggregation
- Powertrain Cost File (str):
The relative or absolute path to the powertrain cost file, loaded by user-definable
PowertrainCost
class defined in the module specified by the file header, e.g.context.powertrain_cost_frm
- Glider Cost File (str):
The relative or absolute path to the vehicle glider cost file, loaded by
context.glider_cost
- Body Styles File (str):
The relative or absolute path to the body styles file, loaded by
context.body_styles
- Mass Scaling File (str):
The relative or absolute path to the mass scaling file, loaded by
context.mass_scaling
- Workfactor Definition File (str):
The relative or absolute path to the workfactor definition file, loaded by
policy.workfactor_definition.WorkFactor
- Session Settings:
Decorator, not evaluated
- Enable Session (TRUE or FALSE):
If
TRUE
then run the session(s)- Session Name (str):
Session Name
- Session Policy Alternatives Settings:
Decorator, not evaluated
- Drive Cycle Weights File (str):
The relative or absolute path to the drive cycle weights file, loaded by
policy.drive_cycle_weights.DriveCycleWeights
- Drive Cycle Ballast File (str):
The relative or absolute path to the drive cycle ballast file, loaded by
policy.drive_cycle_ballast.DriveCycleBallast
- Drive Cycles File (str):
The relative or absolute path to the drive cycles file, loaded by
policy.drive_cycles.DriveCycles
- GHG Credit Params File (str):
The relative or absolute path to the GHG credit parameters file, loaded by
policy.credit_banking.CreditBank
- GHG Credits File (str):
The relative or absolute path to the GHG credits file, loaded by
policy.credit_banking.CreditBank
- GHG Standards File (str):
The relative or absolute path to the GHG Standards / policy targets file, loaded dynamically by the
VehicleTargets
class defined in the module specified by the file header, e.g.policy.targets_footprint
- Off-Cycle Credits File (str):
The relative or absolute path to the off-cycle credits file, loaded by user-definable
OffcycleCredits
class defined in the module specified by the file header, e.g.policy.offcycle_credits
- Policy Fuel Upstream Methods File (str):
The relative or absolute path to the policy fuel upstream methods file, loaded by
policy.upstream_methods.UpstreamMethods
- Policy Utility Factor Methods File (str):
The relative or absolute path to the policy utility factor methods file, loaded by
policy.utility_factor_methods.UtilityFactorMethods
- Policy Fuels File (str):
The relative or absolute path to the policy fuels file, loaded by
policy.policy_fuels.PolicyFuel
- Production Multipliers File (str):
The relative or absolute path to the production multipliers file, loaded by
policy.incentives.Incentives
- Regulatory Classes File (str):
The relative or absolute path to the regulatory classes file, loaded dynamically by the RegulatoryClasses class defined in the module specified by the file header, e.g.
policy.regulatory_classes
- Required Sales Share File (str):
The relative or absolute path to the required sales share file, loaded by
policy.required_sales_share.RequiredSalesShare
- Context Implicit Price Deflators File (str):
The relative or absolute path to the implicit price deflators file, loaded by
context.ip_deflators
DEVELOPER SETTINGS
Developer settings can be specified by defining a row in the format settings.attribute_name
where attribute_name
is an attribute of the OMEGASessionSettings class. In fact, all the default rows could be specified as ‘developer’
settings as well. Use caution when using developer settings, as there are no guardrails to their use and
inappropriate settings may create unexpected behavior.
- validate_predefined_input(input_str, valid_inputs)
Validate the input string against set or dictionary of valid inputs. If
valid_inputs
is a set theinput_str
is checked for inclusion and returned, ifvalid_inputs
is a dict, the value associated with theinput_str
key is returned.- Parameters:
input_str (str) – the string to be validated
valid_inputs (set, dict) – set or dict of valid inputs
- Returns:
Raises Exception if
input_str
not invalid_inputs
or ifvalid_inputs
is not a set or dict, elseinput_str
ifvalid_inputs
is a set, elsevalid_inputs[input_str]
ifvalid_inputs
is a dict.
- is_absolute_path(source_file_path)
Check if source file path is absolute (as opposed to relative). Wrapper for
os.path.isabs()
- Parameters:
source_file_path (str) – file path
Returns: True if file path is absolute
- class OMEGABatchObject(name='', analysis_final_year=None)
Bases:
OMEGABase
Manages batch-level settings and contains a list of sessions.
- __init__(name='', analysis_final_year=None)
Create an
OMEGABatchObject
- Parameters:
name (str) – the name of the batch
analysis_final_year (int) – optional externally-provided analysis final year, otherwise the analysis final year is determined by the batch file
- force_numeric_user_params()
Force certain user batch inputs to be numeric values. List of numeric params must be updated manually when new numeric params are added to the batch settings.
- Returns:
Nothing, changes
self.dataframe
values to numeric values as required
- force_numeric_developer_params()
Force certain developer batch inputs to be numeric values. List of numeric params must be updated manually when new numeric params are added to the batch settings.
- Returns:
Nothing, changes
self.dataframe
values to numeric values as required
- read_parameter(param_name)
Read batch-level parameter, setting applies to all sessions.
- Parameters:
param_name (str) – the name of the parameter to read
- Returns:
The value of the batch setting, taken from the first data column of the batch file
- parse_parameter(param_name, session_num)
Returns the evaluated value of the requested row (
param_name
) and column (session_num
) from the batch file.- Parameters:
param_name (str) – the name of the parameter to evaluate
session_num (int) – which session to evaluate, the first session is session
0
- Returns:
The raw value,
True
for ‘TRUE’ andFalse
for ‘FALSE’, or the valid python object created by evaluating the raw parameter string (i.e. for tuples or dicts in the batch file inputs)
- set_parameter(param_name, session_num, value)
Set the value of a given parameter for a given session in the batch dataframe
- Parameters:
param_name (str) – the name of the parameter to evaluate
session_num (int) – which session to set the value of, the first session is session
0
value – the value to be set
- Returns:
Nothing, sets the value for the parameter in the given session in the batch dataframe
- parse_session_params(session_num, verbose=False)
Parse session params and determine the full factorial dimensions of the session
- Parameters:
session_num (int) – the number of the session to parse, the first session is session
0
verbose (bool) – enables additional console output if
True
- Returns:
The full factorial dimensions of the given session, e.g. (1,1,2,1…)
- parse_batch_params(verbose=False)
Parse settings for each session and return the full factorial dimensions of all sessions
- Parameters:
verbose (bool) – enables additional console output if
True
- Returns:
A list of tuples of the full factorial dimensions of each session, e.g. [(1,1,2,1…), (1,2,2,1…)]
- expand_dataframe(verbose=False)
Expand dataframe as necessary, creating new session names that represent the multi-valued parameters.
- Parameters:
verbose (bool) – enables additional console output if
True
- Returns:
Nothing, but sets the batch dataframe to the newly expanded dataframe, raises Exception if multiple values are found in a parameter that does not support multiple values
- get_batch_settings()
Get batch settings, settings apply to all sessions
- Returns:
Nothing, updates
self.settings
- num_sessions()
Get the number of sessions
- Returns:
The number of sessions in the batch
- add_sessions(verbose=True)
Create an
OMEGASessionObject
for each session in the batch file and add it to theself.sessions
list- Parameters:
verbose (bool) – enables additional console output if
True
- Returns:
Nothing, updates
self.sessions
list
- class OMEGASessionObject(name)
Bases:
OMEGABase
Holds settings and information for a single OMEGA simulation session.
- __init__(name)
Create an
OMEGASessionObject
- Parameters:
name (str) – the name of the session
- read_parameter(param_name, default_value=None)
Read a parameter from the batch dataframe, if present in the batch file, or set it to a default value. Raises an Exception if the parameter is not present and no default value is provided
- Parameters:
param_name (str) – the name of the parameter to read
default_value – optional default value for the parameter if it’s not provided by the batch file
- Returns:
The value of the parameter, or raises an Exception on error
- get_session_settings(session_num)
Set the session number, get the name of the session and whether it is enabled or not. Set the output path of the session.
- Parameters:
session_num (int) – the session to get settings for, the first session is session
0
- Returns:
Nothing, updates session attributes
- get_user_settings()
Get non-developer settings for the session from the batch.
- Returns:
Nothing, updates
self.settings
- get_developer_settings()
Get developer settings for the session from the batch.
- Returns:
Nothing, updates
self.settings
- init(verbose=False)
Get user and developer settings for the session
- Parameters:
verbose (bool) – enables additional console output if
True
- Returns:
Nothing, updates
self.settings
- run()
Initialize and run the session
- Returns:
The result of running the session
See also
omega_model.omega.run_omega()
- validate_folder(batch_root, batch_name='', session_name='')
Confirm the existence of a batch folder (bundle folder or subfolder), create it if it doesn’t exist. Raises an Exception on error
- Parameters:
batch_root (str) – the root of the folder to validate
batch_name (str) – optional argument, the name of the batch
session_name (str) – optional argument, the name of the session
- Returns:
The pathname of the folder, e.g. ‘/Users/omega_user/Code/GitHub/USEPA_OMEGA2/bundle/’
- class OMEGABatchCLIOptions
Bases:
OMEGABase
Stores command-line interface arguments
Attempts to get the IP address of the computer for use with
dispy
parallel processing and logs the start time of batch processing for timestamping the batch and sessions- __init__()
Create an OMEGABatchCLIOptions, get the IP address of the computer and log the start time of batch processing.
- run_bundled_sessions(options, remote_batchfile, session_list)
Run a bundled batch. Bundling copies the source code and all input files to a single directory structure that contains everything needed to run the batch at any time without any external dependencies (except of course a Python install with the required packages)
- Parameters:
options (OMEGABatchCLIOptions) – the command line arguments, contains the path to the remote batch, etc
remote_batchfile (str) – the name of the remote batch file, e.g. ‘2021_08_26_15_35_16_test_batch.csv’
session_list (list) – a list containing the session number(s) to run from the remote batch, e.g.
[0]
or[0, 1, 4, ...], etc
- Returns:
The
OMEGABatchObject
created to run the remote batch
- run_omega_batch(no_validate=False, no_sim=False, bundle_path=None, no_bundle=False, batch_file='', session_num=None, verbose=False, timestamp=None, show_figures=False, dispy=False, dispy_ping=False, dispy_debug=False, dispy_exclusive=False, dispy_scheduler=None, local=False, network=False, analysis_final_year=None)
The top-level entry point for running a batch with the given settings, called from the GUI with a dictionary of arguments. Reads the source batch file, expanding factorially where there are multi-valued parameters, bundles the source code and input files to a common directory and runs the batch from there. Also handles parallel processing via
dispy
options- Parameters:
no_validate (bool) – don’t validate (ensure the existence of) source files
no_sim (bool) – skip simulation if
True
, otherwise run as normal. Typically not used except for debuggingbundle_path (str) – the full path to the bundle folder, e.g. ‘/Users/omega_user/Code/GitHub/USEPA_OMEGA2/bundle’
no_bundle (bool) – don’t bundle files if
True
, else bundlebatch_file (str) – the path name of the source (original, non-expanded, non-bundled) batch file, e.g. ‘omega_model/test_inputs/test_batch.csv’
session_num (int) – the number of the session to run, if
None
all sessions are runverbose (bool) – enables additional console and logfile output if
True
timestamp (str) – optional externally created timestamp (e.g. from the GUI)
show_figures (bool) – output figure windows are created when
True
, otherwise figures are only save to filesdispy (bool) – enables parallel processing via the
dispy
Python package whenTrue
dispy_ping (bool) – ping
dispy
nodes ifTrue
anddispy
isTrue
dispy_debug (bool) – enables additional console output for investigating
dispy
behavior whenTrue
dispy_exclusive (bool) – if
True
then thedispy
node runs a non-shareddispy
clusterdispy_scheduler (str) – the name / IP address of a shared
dispy
scheduler, available whendispy_exclusive
isFalse
local (bool) – if
True
then rundispy
parallel processing on the local machine only, no network nodesnetwork (bool) – if
True
then allowdispy
parallel processing on networked nodesanalysis_final_year (int) – optional override for the analysis final year batch parameter
- Returns:
Nothing
7.3.5. omega_model.postproc_session module
post-compliance-modeling output generation (charts, summary files, etc)
CODE
- run_postproc(iteration_log, credit_banks)
Generate charts and output files for a single simulation
- Parameters:
iteration_log (DataFrame) – dataframe storing information on producer-consumer iteration
credit_banks (dict of CreditBanks) – credit banking information per compliance_id
- Returns:
Results summary DataFrame
- plot_effects(calendar_years, physical_effects_df)
Plot physical effects and aggregate vehicle stock data by calendar year.
- Parameters:
calendar_years ([years]) – list of calendar years
physical_effects_df (DataFrame) – contains physical effects data
- Returns:
dict of physical effects data for the vehicle stock aggregated by calendar year
- plot_cert_co2e_gpmi(calendar_years)
Plot cert CO2e g/mi versus model year, by market class and market category.
- Parameters:
calendar_years ([years]) – list of model years
- Returns:
dict of average cert co2e g/mi data by total, market class and market category
- plot_cert_direct_oncycle_co2e_gpmi(calendar_years)
Plot cert direct oncycle CO2e g/mi versus model year, by market class and market category.
- Parameters:
calendar_years ([years]) – list of model years
- Returns:
dict of average cert co2e g/mi data by total, market class and market category
- plot_cert_direct_kwh_pmi(calendar_years)
Plot vehicle cert direct kWh/mi v. model year, by market class and market category.
- Parameters:
calendar_years ([years]) – list of model years
- Returns:
dict of average cert direct kWh/mi data by total, market class and market category
- plot_target_co2e_gpmi(calendar_years)
Plot cert CO2e g/mi versus model year, by market class and market category.
- Parameters:
calendar_years ([years]) – list of model years
- Returns:
dict of average cert co2e g/mi data by total, market class and market category
- plot_vehicle_cost(calendar_years)
Plot average vehicle cost v. model year, by market class and market category, across all manufacturers.
- Parameters:
calendar_years ([years]) – list of model years
- Returns:
dict of average vehicle cost data by total, market class and market category
- plot_manufacturer_vehicle_cost(calendar_years, compliance_id)
Plot vehicle cost v. model year, by market class and market category, for a single manufacturer.
- Parameters:
compliance_id (str) – manufacturer name, or ‘consolidated_OEM’
calendar_years ([years]) – list of model years
- Returns:
dict of average vehicle cost data by total, market class and market category for the given manufacturer
- plot_vehicle_generalized_cost(calendar_years)
Plot manufacturer vehicle generalized cost v. model year, by market class and market category, for a single manufacturer.
- Parameters:
calendar_years ([years]) – list of model years
- Returns:
dict of average generalized cost data by total, market class and market category
- plot_vehicle_megagrams(calendar_years)
Plot vehicle cert CO2e Mg v. model year, by market class and market category.
- Parameters:
calendar_years ([years]) – list of model years
- Returns:
dict of vehicle cert CO2e Mg data by total, market class and market category
- plot_vehicle_GWh(calendar_years, manufacturer_id=None)
Plot vehicle cert CO2e Mg v. model year, by market class and market category.
- Parameters:
calendar_years ([years]) – list of model years
manufacturer_id (str) – manufacturer id
- Returns:
dict of vehicle cert CO2e Mg data by total, market class and market category
Plot absolute market shares v. model year, by market class, market category, context size class and reg class.
- Parameters:
calendar_years ([years]) – list of model years
total_sales ([sales]) – list of total sales by model year
- Returns:
dict of market share results, by market class, market category, context size class and reg class.
Plot absolute market shares v. model year, by market class, market category, context size class and reg class, for a single manufacturer.
- Parameters:
calendar_years ([years]) – list of model years
compliance_id (str) – manufacturer name, or ‘consolidated_OEM’
total_sales ([sales]) – list of total sales by model year
- Returns:
dict of market share results, by market class, market category, context size class and reg class, for the given manufacturer
- plot_total_sales(calendar_years, compliance_ids)
Plot vehicle sales v. model year, for all manufacturers.
- Parameters:
compliance_ids ([strs]) – list of manufacturer names, e.g. [‘OEM_A’, ‘OEM_B’, …]
calendar_years ([years]) – list of model years
- Returns:
tuple of context sales, total sales, and manufacturer sales by model year (context_sales, total_sales, manufacturer_sales)
- plot_manufacturer_compliance(calendar_years, compliance_id, credit_history)
Plot manufacturer initial and final cert CO2e Mg, including the effect of credit transfers.
- Parameters:
credit_history (CreditBank) –
compliance_id (str) – manufacturer name, or ‘consolidated_OEM’
calendar_years ([years]) – list of model years
- Returns:
tuple of calendar year cert co2e Mg, model year cert co2e Mg, cert target co2e Mg, total cost in billions (calendar_year_cert_co2e_Mg, model_year_cert_co2e_Mg, target_co2e_Mg)
- plot_compliance(calendar_years, compliance_id, target_co2e_Mg, calendar_year_cert_co2e_Mg, model_year_cert_co2e_Mg)
Plot compliance target Mg, calendar year cert Mg and model year compliance Mg
- Parameters:
calendar_years (list) – list of years to plot
compliance_id (str) – manufacturer name, or ‘consolidated_OEM’
target_co2e_Mg (list) – list of target co2e Mg
calendar_year_cert_co2e_Mg (list) – list of calendar year cert co2e Mg
model_year_cert_co2e_Mg (list) – list of model year compliance co2e Mg
- plot_iteration(iteration_log, compliance_id)
Plot producer-consumer iteration data.
- Parameters:
compliance_id (str) – manufacturer name, or ‘consolidated_OEM’
iteration_log (DataFrame) – iteration data
8. Distribution and Support Policy for EPA Software
8.1. Copyright Status
The United States (U.S.) Government retains a non-exclusive, royalty-free license to publish or reproduce these software products and associated documents, or allow others to do so, for U.S. Government purposes. These software products and documents may be freely distributed and used for non-commercial, scientific, and/or educational purposes. Commercial use of these software products and documents may be protected under the U.S. and Foreign Copyright Laws. Individual documents on this server may have different copyright conditions, and that will be noted in those documents.
8.2. Downloadable Documents
A complete copy of this documentation is available in various formats and is downloadable using the following links:
This documentation is also available online at omega2.readthedocs.io/en/2.5.0
8.3. Disclaimer of Liability
With respect to this multimedia system of HTML pages and the EPA software products and their documentation, neither the U.S. Government nor any of their employees, makes any warranty, express or implied, including the warranties of merchantability and fitness for a particular purpose, or assumes any legal liability or responsibility for the accuracy, completeness, or usefulness of any information, apparatus, product, or process disclosed, or represents that its use would not infringe privately owned rights.
8.4. Disclaimer of Software Installation/Application
Execution of any EPA installation program, and modification to system configuration files must be made at the user’s own risk. Neither the U.S. EPA nor the program author(s) can assume responsibility for program modification, content, output, interpretation, or usage.
EPA installation programs have been extensively tested and verified. However, as for all complex software, these programs may not be completely free of errors and may not be applicable for all cases. In no event will the U.S. EPA be liable for direct, indirect, special, incidental, or consequential damages arising out of the use of the programs and/or associated documentation.