Contents
Overview
This is a description of the prototype for the OpenKnee SimTK web interface and files required to allow users to submit a simulation to a cloud computing server and retrieve the results from that simulation.
Simulation Files
GENERAL FILE DESCRIPTIONS
LEGEND: * = wildcard = any string, <*> = variable string or argument, [*] = optional argument(s)
submit_simulation.py
DESCRIPTION: main Python script to submit simulation on cloud server
FILE TYPE: text file
MUTABLE BY USER: no
LOCATION: stored somewhere in SimTK SVN repository
USAGE:
./submit_simulation.py <path/to/febio> <model.feb> [<path/to/modify_model.py> <modify_model.cfg>]
febio*
DESCRIPTION: FEBio program to run simulation
FILE TYPE: binary executable, OS dependent, for example:
- Linux, 64-bit: febio.lnx64
- Windows: febio.exe
- Mac: ???
MUTABLE BY USER: no
LOCATION: Not sure yet where this should be stored. Ahmet says we may not be able to store it on the SimTK SVN repository and transfer to the cloud server to run simulations due to potential licensing restrictions of FEBio. Therefore, it should be stored on the cloud server somewhere???
DOWNLOAD FROM: http://www.febio.org/
also see: Infrastructure/SimulationSoftware
NOTE: When a new version of FEBio is downloaded, the filename does not include the version number. To allow the capability to provide multiple versions to the user, the FEBio executable could be renamed as follows:
- for FEBio, version 1.6.0, for example:
- rename febio.lnx64 to febio_v1.6.0.lnx64
- for FEBio, version 1.6.0, for example:
<model>.feb
DESCRIPTION: Predefined FEBio model file
FILE TYPE: text file
MUTABLE BY USER: no
LOCATION: stored somewhere in SimTK SVN repository (most likely, wherever the <model>.feb file is stored)
ASSOCIATED FILES: modify_<model>.py, modify_<model>.cfg
modify_<model>.py
DESCRIPTION: Python script to modify the model file
FILE TYPE: text file
MUTABLE BY USER: no
LOCATION: stored somewhere in SimTK SVN repository (most likely, wherever the <model>.feb file is stored)
NOTE: this is a default file associated with <model>.feb, though may eventually be universal for all models
modify_<model>.cfg
DESCRIPTION: configuration file specifying parameters of the model to modify
FILE TYPE: text file
MUTABLE BY USER: yes
LOCATION: stored somewhere in SimTK SVN repository
NOTE: this is a default file associated with <model>.feb
EXAMPLE FILES
Example files to allow development of the prototype for the web user interface and submission of simulations are as follows:
submit_simulation.py
model.feb
modify_model.py
modify_model.cfg
These files are located in the SimTK SVN repository at:
Web Interface
JOB SUBMISSION INTERFACE DESCRIPTION
Select server
TYPE: drop-down menu
NOTE: only necessary if more than one server option exists
Select FEBio Version
TYPE: drop-down menu
USAGE:
- if only one version of FEBio is available, it can be set as default
- if more than one version, could set the most recent version as default, and allow the user to select an older version
Select model
TYPE: drop-down menu
OPTIONS: model list, associated with available model files in SimTK SVN
Modify model?
TYPE: radio buttons
OPTIONS: Yes, No (default)
Configuration file name
TYPE: text field, inactive (gray), unedittable
DESCRIPTION: displays name of configuration file (modify_<model>.cfg) after model file is selected.
Configuration file text
TYPE: scrollable text field
DESCRIPTION: displays text contents of the configuration (modify_<model>.cfg) file after model file is selected.
OPTIONS:
- if "Modify Model?" = Yes:
- the text field should be active (black) and edittable
- the text field should be inactive (gray)
- if "Modify Model?" = Yes:
User email address
DESCRIPTION: displays the user's default email address associated with their SimTK account
TYPE: text field, either active and edittable, or inactive
JOB SUBMISSION INTERFACE LAYOUT
A visual representation of the user interface including the core components described above is shown below. Note that optional features that aren't immediately necessary, but may be useful in the future, are shown in red.
ADMIN INTERFACE DESCRIPTION
Project administrators should have a means for updating the user interface, e.g., to add new model files to the drop-down list, to add new fields to specify workflow tasks such as post-processing (future item). They may also need to update the results retrieval interface, depending on how general this is.
-- craigbennetts 2013-12-18 20:10:55 A proposed solution could be to provide the administrator access to a page that is essentially the same as the "JOB SUBMISSION INTERFACE LAYOUT" (refer to figure above) but which has an additional button next to the drop-down model menu (shown in green in the figure above; => green = admin components of GUI) for the administrator to select a model file from somewhere the repository and add it to the list in the drop down menu. If this proposed solution is not easy or feasible, any other solution is fine.
It may also be necessary to allow the administrator to select the associated modify_<model>.cfg file (if there may be more than one associated with the <model>.feb), or it could be associated by default, if there is a fixed filenaming convention between <model>.feb and modify_<model>.cfg (and possibly modify_<model>.py). Therefore, there could be another admin "add" button associated with the modify_<model>.cfg file (and possibly another field and "add" button for modify_<model>.py if there may be more than one assoicated with the <model>.feb file).
RESULTS RETRIEVAL INTERFACE DESCRIPTION
Users will receive an email when their results are ready. They can then use a Web-based interface to retrieve their results. Considerations: How long will results be available? Need to set a time limit on this.
-- craigbennetts 2013-12-18 20:10:55 I do not have a clear idea of how the associated GUI for results retrieval should be designed. It will most likely be easier for whoever who is familar with and going to implement the web interface to determine what is best means of achieving this. This will be dependent on where files will be stored after the simulation has completed
Procedure to Run Simulation
1. User Selections on Web Interface
In order to submit a simulation through the web interface, a user should be logged in to SimTK. This will provide access to the user information, e.g. email address, to notify them when their simulation is complete and available for download.
User will make selections on web interface as described above.
2. Transfer Files to Cloud Server
Transfer the required default and user selected/specified files into the same folder (for example) on the cloud server:
- sumbit_simulation.py
- specified version of FEBio, of the appropriate type for the server:
- Linux, 64-bit: febio.lnx64
- Windows: febio.exe
- Mac: ???
<model>.feb
If "Modify Model?" = Yes:
then transfer modify_<model>.py and the user-editted version of modify_<model>.cfg
3. Run Simulation on Cloud Server
Depending on the selected/specified set of input files, there are 2 options to submit the simulation on the cloud server:
If "Modify Model?" = No, the usage and input arguments are:
./submit_simulation.py <path/to/febio> <model.feb>
For the provided example files, and assuming that all files were transferred to the same folder on a Linux server, run:./submit_simulation.py ./febio.lnx64 model.feb
Else, if "Modify Model?" = Yes, the usage and input arguments are:
./submit_simulation.py <path/to/febio> <model.feb> <path/to/modify_model.py> <modify_model.cfg>
For the provided example files, and assuming that all files were transferred to the same folder on a Linux server, run:./submit_simulation.py ./febio.lnx64 model.feb ./modify_model.py modify_model.cfg
4. Retrieve Results from Cloud Server
Once the simulation has finished, the user should be notified by email, and the newly created files should be returned to the user somehow. The set of files to return to the user depends on whether the original model was modified or not.
If "Modify Model?" = No:
<model>.log
<model>.xplt
Else, if "Modify Model?" = Yes:
<model>_MOD.feb
<model>_MOD.log
<model>_MOD.xplt
Backend Design Considerations
1. How much time/CPU cycles needed for an average job?
For test cases, on individual PC, it took 13 minutes. Full knee joint runs hours, requiring some 18GB memory.
2. Software installation
a. Dependencies: With FEBio, everything is bundled together, including required libraries.
b. Licensing: ??
c. Maintenance: How to track that the required version(s) of the software are provided? Is this something the infrastructure could arrange so the project admin could be responsible for having the proper version installed?