Report Templates
Introduction
A report template is a text file with the .rtp extension which Adams uses to generate a report. The text surrounded by double braces (for example, {{front_axle_load}}) will be replaced by the appropriate text when generating a report. The contents of the double braces must be the name of a Channel or Metric, as described below.
Report templates are stored in the report_templates.tbl table in each CDB.
Channels and Metrics
The Adams Car Report Dictionary
The Adams Car Report Dictionary is a .csv file which contains the definition for the Channels and Metrics available to report templates. The standard Adams Car Report Dictionary can be found in the "acar" subdirectory of your Adams installation.
Each line in acar_report_dictionary.csv defines an entity which can be used in a report template. The type of entity is indicated in the first column of the row.
Channels
Channels are the conduit between the results of an analysis and the reporting framework. They are defined as follows:
Column | Name | Description |
|---|
1 | Type | Channel |
2 | Name | The name with which you'll reference this channel in report templates and Metrics |
3 | Component Name | The name of a result set component |
4 | Units (optional) | Indicates the units of the results data |
5 | Description (optional) | A description of what this Channel represents |
For example, Channels representing normal tire forces could be defined as follows:
Type | Name | Component Name | Units | Description |
|---|
Channel | lftforce_normal | til_wheel_tire_forces.normal_front | N | LF Tire Force, normal |
Channel | rftforce_normal | tir_wheel_tire_forces.normal_front | N | RF Tire Force, normal |
Channel | lrtforce_normal | til_wheel_tire_forces.normal_rear | N | LR Tire Force, normal |
Channel | rrtforce_normal | tir_wheel_tire_forces.normal_rear | N | RR Tire Force, normal |
Metrics
Metrics allow you to process results data and customize how it will be formatted in a report.
There are several varieties of Metric which are explained below:
1. Metric
The basic Metric takes some number of Channels as inputs, performs some predefined processing on the Channel data, and then outputs a single numerical value. They are defined as follows:
Column | Name | Description |
|---|
1 | Type | Metric |
2 | Name | The name with which you'll reference this Metric in report templates |
3 | Description (optional) | A description of what the Metric represents |
4 | Compute Function | Python command that processes the input data |
5 | Input Channels | An ordered list of Channels |
6 | Units (optional) | Indicates the units of the output |
The Compute Function allows you to specify a Python command to execute which uses the data from a Channel. The Compute Function should contain pairs of braces indicating where in the command the Channel data should be used. Moving left to right, each pair of braces will be replaced with the data from the corresponding Channel from the Input Channel list. Note that the data returned by the Channel will be of type list.
The namespace in which the Compute Function is executed can be assumed to contain the standard built-in Python functions, every name from the math module, and the numpy module.
The following examples reference the Channels defined above:
Type | Name | Description | Compute Function | Input Channels |
|---|
Metric | total_tire_force_normal | Total tire forces | sum([last({}),last({}),
last({}),last({})]) | lftforce, rftforce, lrtforce, rrtforce |
Metric | left_tire_force_normal | Sum of left tire forces | sum([last({}),last({})]) | lftforce, lrtforce |
Metric | right_tire_force_normal | Sum of right tire forces | sum([last({}),last({})]) | rftforce, rrtforce |
2. TableMetric
A TableMetric can be used to display a table in a report. You may specify a Channel as the independent data for the table, and some number of Channels as the dependent data. Similar to a basic Metric, a TableMetric is defined as follows:
Column | Name | Description |
|---|
1 | Type | Metric |
2 | Name | The name with which you'll reference this Metric in report templates |
3 | Description (optional) | A description of what the Metric represents |
4 | Compute Function | print_table({}, [{}, {}], increment=_) |
5 | Input Channels | An ordered list of Channels. The first listed Channel is used as the independent Channel. The remaining Channels are used as independent Channels |
6 | Units (optional) | Indicates the units of the output |
Note that the Compute Function must be formatted like
print_table({}, [{}, {}], increment=0.1)
You may specify an increment of your choice. The increment indicates the interval size at which to sample the independent data.
The following is an example of a TableMetric:
Type | Name | Description | Compute Function | Input Channels |
|---|
TableMetric | handling_table | Handling variables | print_table({}, [{}, {}], increment=0.1) | chassis_accel_lat, steering_wheel_angle, steering_wheel_torque_testrig, chassis_roll_angle, chassis_vel_yaw |
3. PolyMetric
A PolyMetric computes a fitted polynomial approximating the relationship between a pair of data sets. They are defined as follows:
Column | Name | Description |
|---|
1 | Type | PolyMetric |
2 | Name | The name with which you'll reference this Metric in report templates |
3 | Description (optional) | A description of what the Metric represents |
4 | Y Channel | The dependent data Channel |
5 | X Channel | The independent data Channel |
6 | Order | The maximum order of polynomial to compute. Must be between zero and the length of the result sets. |
When you define a PolyMetric, another set of Metrics called PolynomialCoefficients are automatically created as well, representing the individual coefficients of the PolyMetric. A PolynomailCoefficient can be referenced by adding a colon followed by the order of the desired coefficient. For example ltoe_wheel_travel_polyfit:2 computes the order-two coefficient of ltoe_wheel_travel_polyfit.
When included in a report template, a PolyMetric will be displayed in the form
A + Bx^1 + Cx^2 + ...
The following examples define PolyMetrics that approximate toe angle as a function of wheel travel:
Type | Name | Description | Y Channel | X Channel | Order |
|---|
PolyMetric | ltoe_wheel_travel_poly | Left toe vs. wheel travel (2nd order polynomial) | ltoe | liwtravel | 2 |
PolyMetric | rtoe_wheel_travel_poly | Right toe vs. wheel travel (2nd order polynomial) | rtoe | riwtravel | 2 |
4. CustomMetric
A CustomMetric allows for more advanced processing by allowing you to call code from an external Python script that you have written. CustomMetrics are defined as follows:
Column | Name | Description |
|---|
1 | Type | CustomMetric |
2 | Name | The name with which you'll reference this Metric in report templates |
3 | Description (optional) | A description of what the Metric represents |
4 | Compute Function | Python command that processes the input data |
5 | Input Channels | An ordered list of Channels |
6 | Units (optional) | Indicates the units of the output |
7 | Unused | |
8 | Python File | The name of the Python script containing your code |
Example Report Template
The following is an example of an Adams Car report template:
=====================================================================
= FULL VEHICLE ANALYSIS RESULTS =
=====================================================================
*** INITIAL CONDITIONS ***
Left Front Tire Load = {{lftforce_normal.first}}
Right Front Tire Load = {{rftforce_normal.first}}
Left Rear Tire Load = {{lrtforce_normal.first}}
Right Rear Tire Load = {{rrtforce_normal.first}}
Front Axle Load = {{front_axle_load}}
Rear Axle Load = {{rear_axle_load}}
Total Vehicle Weight = {{total_vehicle_weight}}
Weight Distribution (% Front) = {{weight_distribution_front}}
Initial Vehicle Velocity = {{chassis_velocity}}
A report generated from this report template would look like the following:
=====================================================================
= FULL VEHICLE ANALYSIS RESULTS =
=====================================================================
*** INITIAL CONDITIONS ***
Left Front Tire Load = 3159.3016 (N)
Right Front Tire Load = 3145.1024 (N)
Left Rear Tire Load = 4345.7306 (N)
Right Rear Tire Load = 4331.2971 (N)
Front Axle Load = 6304.4040 (N)
Rear Axle Load = 8677.0278 (N)
Total Vehicle Weight = 14981.4318 (N)
Weight Distribution (% Front) = 42.0815 (%)
Initial Vehicle Velocity = 69.9958 (km/h)
Report File: test_dlc.rpt
Analysis File: test_dlc.res
Channel Dictionary: C:\Program Files\MSC.Software\Adams\2024_1\acar\acar_report_dictionary.csv
Template File: C:/Program Files/MSC.Software/Adams/2024_1/acar/shared_car_database.cdb\report_templates.tbl\full_generic.rtp
Date Created: 2019-04-10 17:20:04
User Name: tpeters