#acl +All:read Default
#format wiki
#language en
<<TableOfContents>>
== 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'''.
{{attachment:CloudComputingPrototypeGUI.png}}
=== 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]] <<DateTime(2013-12-18T20:10:55Z)>> 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]] <<DateTime(2013-12-18T20:10:55Z)>> 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 ===