Canopy Integration
The Canopy integration in HH Data Management allows users to trigger Canopy simulations and visualize their results in HH Data Management.
Canopy Simulation Configuration
The Canopy simulation configuration is used define:
- the type of Canopy study to run
- how the inputs for the Canopy simulation will be created
- how the results of the Canopy simulation will be processed
- how the feedback from the Canopy integration should be communicated back to HH Data Management
The Canopy simulation configuration is defined on the account management website.
The Canopy Config page is only available to users with Admin level permissions on the website.
Multiple configurations can be created and they will be listed on this page. New configurations can be created by clicking the + symbol.
When creating or editing an existing configuration a dialog will pop up:
General information
- Name: the name of the profile
- Study type: the type of Canopy study to be run
Worksheets
Studies can, optionally, be saved to a Canopy Worksheet.
- Write Study Info To Worksheet: if selected, the Canopy study info for the simulation will be saved to the Canopy Worksheet that is specified by the Path To Worksheet Id.
- Path To Worksheet Id: the path (as an HH Data Management expression, relative to the setup) to the parameter that stores the worksheet id where the study info will be written. For example if the ID is stored on the event in a parameter called
WorksheetIdthen, the path would beEvent.WorksheetId.
- Path To Worksheet Id: the path (as an HH Data Management expression, relative to the setup) to the parameter that stores the worksheet id where the study info will be written. For example if the ID is stored on the event in a parameter called
Simulation status
All fields in this section are optional (i.e. any of them can be left blank in which case the information will not be available in HH Data Management).
The status parameters are used to provide feedback on the currently running canopy simulation. Parameters should be created on the relevant setup definition, and their names entered here. These parameters can be shown on the setup sheet CID.
- Simulation Status Parameter Name: a string parameter; this will show a one word status of the current simulation. The possible values are:
- Requested: the request to run a Canopy simulation has been received by the HH Data Management server and the simulation will be started soon
- Simulation start failed: there was an error when sending the simulation request to the Canopy API
- Simulation started: the simulation has been successfully submitted to the Canopy API and the simulation is running
- Simulation running: the simulation is currently running on Canopy and the HH Data Management server is waiting for it to complete
- Failed to check status: HH Data Management wasn't able to retrieve the information about the current simulation
- Simulation completed: the Canopy simulation has completed
- Processing results: HH Data Management is starting to process the simulation results (download the ouputs from Canopy, post process them and upload them to HH Data Management)
- Processing failed: there was an error encountered while processing the results
- Canopy simulation error: the Canopy simulation had errors and did not complete
- Processing completed: HH Data Management has processed all results and the process is now complete
- Simulation Message Parameter Name: a string parameter; in case of a failure state, more information will be given regarding the nature of the error
- Simulation Status Update Time Parameter Name: a DateTime parameter; the last time a status update was received
Further more the three following feedback options are available. Again, there need to be parameters with these names defined on the setup definition for the information to be available.
- Canopy Feedback Error Parameter Name: a string parameter; this will show any errors that were reported by Canopy
- Canopy Feedback Warn Parameter Name: a string parameter; this will show any warnings that were reported by Canopy
- Canopy Feedback Info Parameter Name: a string parameter; this will show any other information that was reported by Canopy
Inputs
General
- Study Name Expression: a math expression that is evaluated on the scope of the setup, that is the name the study will be given in Canopy. If this is left blank then a default name will be used.
- Sim Version Parameter Name: a string parameter on the AccountOptions definition that will store the current version of the Canopy simulation engine. This can then be used if using Json exports to build the Canopy configuration files.
- Use Custom Sim Version: if selected, the Canopy simulation version will be set based on the specified Path To Custom Sim Version.
- Path To Custom Sim Version: the path (as an HH Data Management expression, relative to the setup) to the parameter that stores the custom version of the Canopy simulation engine to use for the study. For example if the ID is stored on the event in a parameter called
CustomSimVersionthen, the path would beEvent.CustomSimVersion.
- Path To Custom Sim Version: the path (as an HH Data Management expression, relative to the setup) to the parameter that stores the custom version of the Canopy simulation engine to use for the study. For example if the ID is stored on the event in a parameter called
- Parameter Name To Save Study Id: a string parameter on the setup definition where the current Canopy study ID can be saved. This is useful for debugging the simulation in the Canopy web UI or when reprocessing results without needing to rerun the Canopy simulation.
Configurations
The available inputs depend on the selected study type. Some configuration types are required and others are optional. For each configuration the first option to select is the Json source. The following options are available, and each option has its own sub options that will appear depending on the selection:
- None: this configuration type won't be added to the simulation
- Stored on Canopy: in this case the configuration is stored on Canopy, and the HH Data Management Canopy integration needs to know the ID of the configuration that should be used.
- Path To Canopy Id: the path (as an HH Data Management expression, relative to the setup) to the parameter that stores the ID of the configuration that is stored on Canopy. For example if the ID is stored on the car in a parameter called
CanopyCarConfigIdthen, the path would beCar.CanopyCarConfigId.
- Path To Canopy Id: the path (as an HH Data Management expression, relative to the setup) to the parameter that stores the ID of the configuration that is stored on Canopy. For example if the ID is stored on the car in a parameter called
- Json export: in this case the configuration will be generated from a HH Data Management Json export and this file will be uploaded to Canopy as part of running the simulation.
- Json export profile: select from a drop down which Json export profile to be used to generate the Json configuration file
- Attached file: in this case the configuration file is stored as an attached file in HH Data Management. This attached file will be uploaded to Canopy as part of running the simulation:
- Attached file name: the name of the attached file parameter where the attached file is stored
Outputs
General
As with the configuration inputs, these inputs will only be available if applicable for the selected study type. These allow additional configurations to be created and used for results processing of additional results in the output. For example, when running an Apex study type, the results from the Straight study will also be included in the results set. By creating an additional Straight sim configuration and referencing it here, the straight results can be processed as part of the Apex sim.
- Additional Straight Simulation Configuration: an additional Canopy configuration that will be used to process the straight sim results
- Additional Apex Simulation Configuration: an additional Canopy configuration that will be used to process the apex sim results
Scalar outputs
Scalar Results Save Option: an option indicating how the scalar results will be processed and saved into HH Data Management
- None: no post processing of the results will be done
- HHDMParameter: the scalar results will be saved into parameters in HH Data Management on the setup definition
Save Original Scalar File: if selected, then the original CSV file from Canopy will be uploaded to HH Data Management into the specified named attached file parameter on the setup definition.
Attached File Name For Original Scalar File: if the option to save the original scalar results file is enabled then this field is used to define the attached file parameter name on the setup where the attached file should be saved
Scalar Results Mappings: a mapping that is used to define which scalar outputs from the simulation will be saved to HH Data Management. The mappings define the name of the parameter in the Canopy scalar results and the name of the parameter in HH Data Management or that will be used in the JSON results structure.
Constraints outputs
- Constraints Results Save Option: an option indicating how the constraints results will be processed and saved into HH Data Management
- None: no post processing of the results will be done
- HHDMParameter: the constraints results will be saved into parameters in HH Data Management on the setup definition
- Save Original Constraints File: if selected, then the original CSV file from Canopy will be uploaded to HH Data Management into the specified named attached file parameter on the setup definition.
- Attached File Name For Original Constraints File: if the option to save the original constraints results file is enabled then this field is used to define the attached file parameter name on the setup where the attached file should be saved
- Constraints Results Mappings: a mapping that is used to define which constraints outputs from the simulation will be saved to HH Data Management. The mappings define the name of the parameter in the Canopy constraints results and the name of the parameter in HH Data Management or that will be used in the JSON results structure.
Authentication
For the HH Data Management Canopy integration to be able to interact with Canopy API, authentication credentials must be provided. These are defined in the backstage options.
Trigger Simulations
To trigger a simulation on Canopy a Canopy Simulation Configuration needs to be created in HH Data Management. Buttons can then be created in HH Data Management (in the setup sheet for example) that when clicked will request a canopy simulation to be run using a specified configuration.
Roadmap
Especially as this feature is still in active development please be sure to report any bugs, undesirable behaviour from the system or general feedback.
Topics that are currently working on:
- visualization of vector results
Topics that we plan to work on in the near-future
- ability to auto trigger simulations (e.g. when a setup parameter changes, automatically trigger a simulation run)