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:

Key	Description
label	The label for the result
results_label	Overrides the label for the result panel.
value	The value of the result
units	The units of the result
info	Tooltip added to the result
hidden	If `true` hide the result
paid_only	Make result only available to paid users
standout	Make the result standout in larger font!
note	Optional note about the result.
hide_in_s3d	Hide the result in the S3D output table.
round	Specify the rounding to appear in results.
integer	Output is an integer (no rounding).

Output Settings#

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

Key	Description
note_style	Either `icon` or `below`.
show_log	Show the log icon.
show_feedback	Show the feedback icon.

Special Result Types#

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

Key	Description
utility	Display result as PASS/FAIL
utility_status	Display result with adjacent PASS/FAIL
utility_boolean	Display result box with PASS (value = 1) & FAIL (value = 0)
heading	Heading Object
error	Error Object
price	Price object with $ symbol
price_euro	Price 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"
}

QD Colors#

RED: #DB2828
GREEN: #21BA45
ORANGE: #F2711C

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:

Global	Purpose
`config_json`	Access the config_json element to access values	`let 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'

Opening S3D Models#

You can give users the option to open S3D models from the Quick Design by returning the s3d_model key in the results.

var output = {
    'report': REPORT,
    's3d_model': s3d_model,
    'results': results_obj
};

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);

Handling Errors#

Use the below code to handle errors:

return ERROR(err_msg)
return ERROR(err_msg, error_title)

caution

Do not use throw new Error

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:

State Management#

The state management helper allows you to access the state object from any context or util.

// calculate.js
state.my_var = "abc";
state.my_fun = foo() => { return "bar"; }

// some_util.js
logger(state.my_fun()) // "bar";
state.my_var = "123";

// other_utils.js
logger(state.my_var) // "123";

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;

}

Layout#

ReportHelpers#

Output#

Output Variable Options#

Output Settings#

Special Result Types#

Custom Boxes#

QD Colors#

Warning Boxes#

Globals#

Other Packages#

SVG Section Dimensions#

SVGCreator Package#

Pretty Print Package#

PrettyPrint.pretty_print.print()#

Set Precision while Printing#

With Trailing Zeros#

Define digits after exponent#

Using engineering notation (only multiples of 3 are used in exponents)#

Using engineering notation (with significant digits instead of digits after decimal)#

PrettyPrint.pretty_print.numberWithCommas()#

SVG Section Dimensions#

Chart JS Integration#

Plotly JS Integration#

Opening S3D Models#

Warnings#

Handling Errors#

caution

Debugging your Code#

Logging:#

State Management#

FULL EXAMPLE#

`PrettyPrint.pretty_print.print()`#

`PrettyPrint.pretty_print.numberWithCommas()`#