API's, batching, and chaining requests
ArupCompute is hosted on a server. Each time you want it to do some work you need to send a request to it. Each request goes through a few stages:
- Packaging up and sending from your computer
- 'Time in flight'
- From your computer to your router
- From your router on the wires of the internet
- Passing through various switching equipment
- Finally being passed into the data centre where ArupCompute runs
- Passed to the actual server that ArupCompute is running on
- Unpacking the request
- Routing to the appropriate library
- Doing the actual work
- Repackaging and sending from the server
- Time in flight
- Unpacking the response
- Giving the answer back to you
There are two major impacts to this:
- Batching requests
- Chaining requests
Batching
Many of these steps involve a certain amount of overhead. For example every request sent over the network has a set of headers as well the payload.
Because of this a large amount of efficiency can be gained by batching requests instead of sending them individually. You will need to design your spreadsheets and scripts with this in mind.
For example in Excel, instead of using Goal Seek on an individual calculation, instead run a large table of calculations at the same time.
In python, instead of optimising in a loop, send off a range to be calculated each time.
How to batch up requests
If you are using the desktop clients (Excel, Grasshopper or Dynamo) batching will be undertaken for you automatically.
If you are using a programming client, or the API directly, you will need to consider how requests are batched.
You may perform a batch calculation using the api/calcrecords
endpoint, setting the isBatch
query param to true
, and passing arrays of values for the calculation inputs.
Note that the request body should look like this:
{
"calculation_input_1": ["input_value_1", "input_value_2", ..."input_value_n"],
"calculation_input_2": ["input_value_1", "input_value_2", ..."input_value_n"]
}
Not like this:
[
{
"calculation_input_1": "input_value_1",
"calculation_input_2": "input_value_1"
},
{
"calculation_input_1": "input_value_2",
"calculation_input_2": "input_value_2"
},
...{
"calculation_input_1": "input_value_n",
"calculation_input_2": "input_value_n"
}
]
The Node.js client for ArupCompute will accept either format (i.e. if you provide the second format it will convert to the first before submitting the request).
Chaining
Because of the response time it is best for performance if more work can be done in a single request. As a calculation user you have little control over this, but as a library author you do. For example provide calculations that perform a number of useful steps one after the other.
If you are a DesignCheck calculation user you can create your own project-specific multiple step engineering processes using CalcBuilder.