| Table of Contents |
|---|
Overview
AMPI offers two main concepts for doing calculations: Scores and Blackboxes. Blackboxes are meant to evaluate one or several part Properties. That means a blackbox looks at the value of one property (can also be several properties if they are correlated) and decides whether that value is rather good (for AM) or rather bad (for AM).
Scores are meant to evaluate one or several Blackboxes, to produce an overall assessment of a part’s characteristics. Through reports and charts, the score results can then be shown to users.
...
Blackboxes and Scores are written in Javascript. For making adjustments to the calculation logic, it is helpful to have some prior exposure to any kind of scriptwriting or programming
Blackboxes
Defining blackboxes
Blackboxes are defined in the admin panel under
...
Slug
Unique identifier of that blackbox. Used to reference this blackbox from a score.
Writing blackbox scripts
A blackbox can be considered a function that returns a value or an object.
...
| Code Block | ||
|---|---|---|
| ||
const propertyValue = variables.custom.qualificationNeeded
switch (propertyValue) {
case true:
return 0.35
case false:
return 1.0
default:
return null
} |
Scores
Scores can aggregate blackbox results into an overall result
Defining scores
Scores are defined in the admin panel under
...
When defining scores, the following fields are available.
Name
The display name of the scoreAssign a meaningful name to the score to recognize it during the whole process of the platform configuration. This field is not displayed in the UI.
Description
Additional description for the score. Currently This field is not displayed anywhere in the UI.
Script
The core of the score is a script written in Javascript
Slug
Unique (alphanumeric) identifier of that the score. Used It is used as part of the column name in the CSV exportsexport functionality.
Filterable
If selected, this score will be available for filtering on the part list. Should only be enabled for numerical scores. Only scores marked as filterable will be included in CSV exports.the CSV export functionality.
Unit of measurement
Append a unit to the score results. This field is used only for non monetary values (e.g. kg, days, etc.); for monetary values, use the field `Is currency`.
FE Multiplier
Used to multiple the score results to the defined factor and visualize the multiplied value in the UI (e.g. multiply by 100 to transform into % a score that is calculated between 0 and 1). The score results is not multiplied in the database nor in the CSV export functionality.
Decimal places
Choose how many digits will be displayed in the UI after the comma for the score results (valid for scores of `Type` numeric).
Is currency
Select this option for monetary scores. When selected, the results are automatically formatted and displayed in the UI as currency, accordingly to the international rules.
This field overwrites the `Unit of measurement`, `FE Multiplier` and `Decimal places`.
Type
Define how to display in the UI the score results, as a text or a number. When text is selected, `Unit of measurement`, `FE Multiplier`, `Decimal places` and `Is currency` are ignored.
Schema
Specify how to render the score results into a specific type of card (i.e. report chart). Options include a table, a list and KPI card.
For reference: https://3yourmind.atlassian.net/wiki/spaces/PD/pages/1373831169/Reports+and+Charts#Defining-Charts
Writing score scripts
A score can be considered a function that returns an object with a result value. The result value can then be displayed in charts.
...
| Code Block |
|---|
// Slug of the blackbox that I want to retrieve const LEAD_TIME_EXACT = 'BbEconLeadTimeExact' // Retrieving blackbox result const value = results[LEAD_TIME_EXACT].result |
Tech and Econ scores
Tech and Econ scores are numerical scores that calculate the technical and economic suitability of a part within a range of [0, 1]. Values towards 0 indicate poor suitability, values towards 1 indicate good suitability for AM.
...
For a complete example of an econ score, see the Appendix
Text scores
The result of text scores is a String (text) - as opposed to numerical scores that produce numerical results. They can be used in charts with the type Text.
...
For a more comprehensive example see the Appendix.
Helper functions
Helper functions are functions that are often used throughout multiple blackboxes or scores. To avoid defining such functions in each blackbox where it is used, they can just be defined once as a helper function. Then all blackboxes and scores can just use them without the need to define them redundantly.
...
| Code Block |
|---|
// valid
function abc() {
return 1;
}
// invalid
return 1; |
How to debug blackboxes and scores
The results of blackbox and score calculations can be verified in several places in the admin panel
Show parts with errors in the calculation
Go to Parts
Home › B3_Ampi › PartsUse the filter option With errors
Any part still visible in the list now has an error somewhere in the calculation
Open the part details
Scroll down to the blackbox results
Check the list of blackboxes for those with an error
...
Overview of all calculation results for one particular part
To see all the score and blackbox results for one particular part, do the following
Go to Parts
Home › B3_Ampi › PartsFind the part that you are interested in and open the details
Scroll down past the properties
You’ll reach a table with all score results for this part and a table with all blackbox results just below.
...
Verifying the calculation results of one score or blackbox for one part
To see detailed results of a score or blackbox including all input variables for one particular part do the following:
Go to Parts
Home › B3_Ampi › PartsFind the part that you are interested in and open the details
Open either Blackbox tester or Score tester
From the list, select the score or blackbox you are interested in
Detailed score and blackbox results of the econ score.
...
Detailed input used in the blackbox and score calculations
...
Triggering recalculation
For performance reasons and to reduce server load, blackbox and score results are only calculated once and then stored for repeated use. If a blackbox or score script is changed, you need to manually trigger a re-calculation of blackbox and score results. It is sufficient to trigger the recalculation once at the end of your editing actions.
...
To trigger a recalculation manually, you can just follow these simple steps:
In any formula perform a zero impact change, e.g.
add a space at the end of a line
add an empty new line
Save your changes
Click Recalculate on the recalculation banner.
Appendix
Example
Full econ score script
...