Calculate File

The calculate.js file is where all the action happens. The calculate file uses javascript. This is where you write the logic that performs the necessary transformations on your input to create your desired output. The calculate.js file must always return an output object based on the format specified below. The calculate.js file also handles all reporting functions, and returns the report that is generated by your calculator.

Layout#

module.exports = function (input_json) {
// Get Input
let { a, b } = input_json;
// Perform Logic
// Per Output Format
let output = {};
// Return Output
return output;
}

ReportHelpers#

ReportHelpers is a library designed to help you format and write reports easily. Find the documentation for ReportHelpers here.

Output#

{
"report": REPORT,
"results": {
"Result A": {
"value": a,
"units": "m",
},
"Result B": {
"value": b,
"units": "kN",
},
"Heading A": {
"label": "My Heading",
"units": "heading",
},
"ur_a": {
"label":"Utility Ratio A", //you can add this label key if you want to use cleaner keys
"value": 1.282,
"units": "utility",
},
"ur_b": {
"label":"Utility Ratio B",
"value": 0.751,
"units": "utility", //this can then be read by the UI to show PASS/FAIL
}
}
}

Output Variable Options#

Each output variable can have the following keys:

KeyDescription
labelThe label for the result
results_labelOverrides the label for the result panel.
valueThe value of the result
unitsThe units of the result
infoTooltip added to the result
hiddenIf true hide the result
paid_onlyMake result only available to paid users
standoutMake the result standout in larger font!
noteOptional note about the result.
hide_in_s3dHide the result in the S3D output table.

Output Settings#

The settings key is used to control certain elements of the output results.

KeyDescription
note_styleEither icon or below.
show_logShow the log icon.
show_feedbackShow the feedback icon.

Special Result Types#

By using the following strings as the units value, special results types can be created.

KeyDescription
utilityDisplay result as PASS/FAIL
utility_statusDisplay result with adjacent PASS/FAIL
utility_booleanDisplay result box with PASS (value = 1) & FAIL (value = 0)
headingHeading Object
errorError Object
pricePrice object with $ symbol
price_euroPrice object with € symbol

Utility Box vs Utility Status Examples

The below image highlights the difference between utility box (default option) and the utility_status result objects.

Utility Color Rules

All utility boxes work with the following rules:

  • < 0.95 = PASS (GREEN)
  • >= 0.95 < 1 >= WARN (ORANGE)
  • >= 1 = FAIL (Red)

Utility Booleans do not have a warn option.

Custom Boxes#

Custom boxes allow you to full customize a utility box with your own text/colors

"Example 1": {
"units": "custom_box",
"value": "Some Text",
"color": "#289DCC"
},
"Example 2": {
"units": "custom_box",
"value": "More Text",
"color": "#db2828"
}

Warning Boxes#

Similar to a custom box with the colors of a warning to ensure consistency.

"Example 1": {
"units": "warning_box",
"value": "Some Text",
},

Globals#

The following globals variables are available in the calculate.js:

GlobalPurpose
config_jsonAccess the config_json element to access valueslet unit = config_json['variable_key']["units"]

Other Packages#

SVG Section Dimensions#

See the SVG Section Dimensions Documentation.

SVGCreator Package#

let svgCreator = SVGCreator;
svgCreator.initialize({
total_height: 100,
total_width: 150,
align: 'left'
});
svgCreator.addText({
text_value: 'TEST SVG CREATOR'
});
svgCreator.addRect({
x: 0,
y: 20,
width: 50,
height: 40,
fill_color: 'green'
});
svgCreator.endSVG();
let svg_html = svgCreator.getSVGHtml();
ReportHelpers.print("", svg_html, "");
REPORT.section.break();

Available Methods

For full documentation see the Quick Design UI Page.

Pretty Print Package#

Option for ability to print numbers nicely

PrettyPrint.pretty_print.print()#

Set Precision while Printing#
PrettyPrint.pretty_print.print(3.92314); => '3.923'
PrettyPrint.pretty_print.print(3.92314, {
"precision": 1,
}); => '3.9'
With Trailing Zeros#
PrettyPrint.pretty_print.print(3.9, {
"precision": 5,
"trailing_zeros": true
}); => '3.90000'
Define digits after exponent#
PrettyPrint.pretty_print.print(3923140000, {
"digits_after_decimal": 5,
"method": "exponential"
}); => '3.92314e9'
Using engineering notation (only multiples of 3 are used in exponents)#
PrettyPrint.pretty_print.print(50000, {
"digits_after_decimal": 2,
"method": "engineering"
}) => '50.00e3';
Using engineering notation (with significant digits instead of digits after decimal)#
PrettyPrint.pretty_print.print(10499000, {
"significant_digits": 4,
"method": "engineering"
}) => '10.40e6';

PrettyPrint.pretty_print.numberWithCommas()#

PrettyPrint.pretty_print.print(0.00006, {
"method": "exponential",
"auto_exp": true
}); => '6.00000e-5'

SVG Section Dimensions#

See the SVG Section Dimensions Documentation.

Chart JS Integration#

See the ChartJS Integration Docs

Warnings#

Quick Design has an inbuilt warn function to help you add warnings to the calculate.js and notify user of potential issues they should be aware of.

To call the warn function follow the example below:

// Warn the user and add a warning block to the calculation report.
warn("My warning", true);
// Warn the user and add a warning block to the calculation report with a reference.
warn("My warning", true, "Some reference");
// Warn the user but DO NOT add a warning block to the calculation report.
warn("My warning", false);

Debugging your Code#

Since the code is running on our server (under a controlled environment) it may be difficult to debug. Errors are caught and returned to the user as a notification and in the actual report:

Logging:#

logger("E = " + youngs_modulus); // Log some values or results.
logger("ENTERED IF STATEMENT"); // Helpful for debugging and quick logging.
logVariables({shape, welded,alloy,Mz}) // Will print a batch of variables.

When you run your calculations, these will be available in the top corner of your code:

Having a detailed log will help both you and the user identify issues in the code:

FULL EXAMPLE#

module.exports = function (input_json) {
ReportHelpers.printInputSummary();
ReportHelpers.heading("Hypotenuse Calculation", 2);
ReportHelpers.print("By Pythagoras Theorem");
let a_squared = Math.pow(a, 2);
let b_squared = Math.pow(b, 2);
let c = Math.sqrt(( a_squared + b_squared )).toFixed(2);
REPORT.block.new();
REPORT.block.addCalculation('[math] C^2 = A^2 + B^2 \\therefore C = \\sqrt{ A^2 + B^2 } [math]');
REPORT.block.addCalculation('[math] C = \\sqrt{ ' + a + '^2 + ' + b + '^2 } [math]');
REPORT.block.addCalculation('[math] C = \\sqrt{ ' + (a_squared + b_squared) + ' } = ' + (c) + '[math]');
REPORT.block.finish();
var output = {
"pass": true,
"report": REPORT,
"results": {
"Missing Side (C)": {
"value": c,
"units": "m",
},
}
}
return output;
}