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

<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:

• https://simtk.org/websvn/wsvn/openknee/aux/cld/prototype/#_aux_cld_prototype_

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
    else, if "Modify Model?" = No:
    • the text field should be inactive (gray)

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?

3. Security to ensure that uploaded files (including those modified by users) are legitimate and will not break the system