Airavata PHP Command Line Student Tutorial
Update
The PHP command line scripts have been moved to the Apache Airavata git repository.
Introduction
An Airavata user or a gateway developer can also exercise using PHP client through command line to execute jobs in the computational Resources.
Prerequisites
- Make sure you have PHP & GIT installed in your machine.
NOTE: The tutorial steps are given for Linux environment.
You Will Learn
- Execution of Airavata API methods using PHP client-command line.
- How to enter/modify input parameters for the methods in command-line.
Tutorial I - Preparation
- Create a folder (ex: SciGaP) in a preferable location in your local machine to clone the PHP samples from GitHub.
- Open the created SciGaP folder (...../ cd SciGaP) and clone the files using GitHuB ‘HTTPS clone URL’
git clone https://git-wip-us.apache.org/repos/asf?p=airavata.git
Once the cloning is completed you would get a completed message. - Open the folder which contains the PHP sample scripts.
SciGaP → airavata/airavata-api/airavata-client-sdks/airavata-php-sdk/src/main/resources/php-cli-samples - client-samples folder contains PHP scripts to exercise currently existing Airavata API methods;
- GetAPIVersion.php (a sanity check)
- add-compute-resources.php
- createProject.php
- updateProject.php
- getAllUserProjects.php
- createExperiment.php
- getExperiment.php
- updateExperiment.php
- cloneExperiment.php
- getAllExperimentsInProject.php
- getAllUserExperiments.php
- launchExperiment.php
- getExperimentStatus.php
- getExperimentOutputs.php
- terminateExperiment.php
- list-application-interfaces.php
- list-compute-resources.php
- airavata-client-api-tester.php
- Apart for the scripts for the API methods the folder contains;
- airavata-client-properties.ini - contains the server. port and timeout period information
- README-PHP-CLI-Examples.txt - Gives the script execution order
- Navigation to working directory;
cd SciGaP/airavata/airavata-api/airavata-client-sdks/airavata-php-sdk/src/main/resources/php-cli-samples
Tutorial II - Sanity Check
- Get Airavata Version
Execute php getAPIVersion.php and confirm the Airavata API version.
Tutorial III - Add Computational Resources
- To add computational resources use script; registerComputeResource.php
- In order to run the script hostName and resourceDescription are passed as command line arguments.
- Format;
php registerComputeResource.php<space><hostName><space><resourceDescription>
- Execute the above and a confirmation message will be prompted along with the resource ID (computResourceId)
Compute Resource<space><computeResourceId><space>is<space>registered! - Tutorial Tryout;
Add other parameters to the script as command line arguments and improve the script.- hostAliases
ipAddresses
Tutorial IV - Create, Update & List Projects
Create Project
- Use; createProject.php to create new projects.
project_owner and project_name can be given as command line arguments.- Format;
php createProject.php<space><project_owner><space><project_name>
- When creating new projects both project_owner and project_name cannot contain spaces.
- Sample values;
project_owner: Thomas
project_name: Test_Project
- Successful creation of project will give confirmation message with the Project ID
Project<space><project_ID><space>is<space>created! - Tutorial tryout;
Add project description as a command-line argument to the existing createProject.php script and execute.
Update Project
- Use; updateProject.php to modify or add project description.
project_ID and project_description are passed into the script as command line arguments.- Format;
php updateProject.php<space><project_ID><space><project_description>
- When updating Projects currently user can only update the project description. Description cannot contain spaces.
- Sample values;
project_ID: Test_Project_4063b440-332a-49af-a6de-aea21d77bb2f
project_description: Test_Airavata_Project
- Successful modification of project will give confirmation message with the Project ID
Project<space><project_id><space>successfully<space>modified. - Tutorial tryout;
Add project name as a command-line argument to the existing updateProject.php script and execute.
List Project
- Verify the existence of the above created project by using getAllUserProjects.php file
- User = Project owner who creates the Project. User name is given as a command line argument.
- Format;
php getAllUserProjects.php <space><user> - Sample values;
user: Thomas
- Execute the file; all the projects created by the given user will get listed with project information.
...
Image - Project Detail Listing
Tutorial V - Create, View , Update & Clone Experiment
Create Experiment
- Create an experiment with above created project using createExperiment.php script. When creating experiment User, Experiment name and Project ID (username, experiment_name, project_ID) are passed as arguments to the script.
- Format;
php createExperiment.php<space><username><space><experiment_name><space><project_ID>
- Changing other parameters require opening the script and modifying and saving values inside the script.
Sample values;
Parameter | Sample Values | NOTE |
---|
Project ID | Test_Project_4063b440-332a-49af-a6de-aea21d77bb2f | Project iD is validated against existing projects Passed as an argument to the script |
Creating User | Thomas | Users are validated against existing Airavata gateway users. Passed as an argument to the script |
Experiment Name | Exp_Test_Project_1 | Not a unique value. Use can enter any value Passed as an argument to the script |
Resource Host ID | trestles.sdsc.edu stampede.tacc.xsede.org | |
Computational Project Account | | |
Total CPU Count | 10 | Number of CPUs required for the experiment |
nodeCount | 10 | Number of nodes required in each CPU |
Number of Threads | 10 | Number of threads per node |
Queue Name | normal | if left blank it will pick default queue |
Wall Time Limit | 10 | This is given in minutes |
JobStartTime | 0 | |
Total Physical Memory | 0 | |
Application ID | SimpleEcho2 | Existing application in the selected resource |
Input Key | echo_input | |
Input Value | echo_output=Hello World | |
Output Key | echo_output | |
- Depending on the computational resource used the resource scheduling data part need to be entered by the user. Other defined resource scheduling parts should be commented.
Image - PHP Script Sample
- Execute the file; experiment will be created and experiment ID will be generated; ID is the unique value which identifies the experiment in Airavata.
- Experiment creation confirmation message;
Experiment<space><exp_ID><space>created!
View Experiment (Search by Experiment ID)
- To search and view above created experiment use getExperiment.php.
- This would list experiment parameters and information about the experiment such as output, number of nodes, status, etc…
- To view the experiment use;
- php getExperiment.php
- Format:
php getExperiment.php<space><exp_ID>
- All experiment related information will be listed along with experiment ID, experiment name, resource, application , user configuration data, etc…
Update Experiment
- To update above created experiment use updateExperiment.php.
- Currently the script modifies only the experiment name, by adding a generated text at the end of the name.
- To modify the experiment use;
- php updateExperiment.php
- Format:
php updateExperiment.php<space><exp_ID>
- Once executed experiment details will be displayed along with the new experiment name.
- Tutorial tryout;
- Modifying the script to update more data in the experiment the same way; Try updating exp_description.
- Update the script to modify existing configuration data by feeding the new values as command line arguments.
Clone Experiment
- To clone above modified experiment use cloneExperiment.php.
- Cloning will create exact copy of the existing experiment with a new experiment ID in CREATED state.
- To clone the experiment use;
- php cloneExperiment.php
- Format:
php cloneExperiment.php<space><exp_ID>
- Experiment modification confirmation message;
- Experiment<space><exp_ID><space>cloned!
- User can clone any experiment created by him/her irrespective of the experiment status.
- User can change existing information by updating the newly created experiment.
- Tutorial tryout;
- Try adding parameters to the script to change other data in the new experiment. E.g.: Exp name, Application, Resource, etc… and execute.
Tutorial VI - Search Experiments
Get All Experiments In Project
- To view all experiments created under one project we use getAllExperimentsInProject.php.
- Format:
php getAllExperimentsInProject.php<space><project_ID>
- All the experiments and their details created using the given project_ID will be listed.
Get All Experiments by User
- To view all experiments created by a single user we use getAllUserExperiments.php.
- Format:
php getAllUserExperiments.php<space><username>
- All the experiments and their details created by the given user/username will be listed.
Search Experiment by Experiment Name
- Experiments can be searched by providing username along with experiment name or part of the experiment name.
- Format;
php search_experiments_by_name.php<space><username><space><experiment_name> - Example;
php search_experiments_by_name.php Test_User Exp
- When the script is executed; all the experiments which has the given text as part of the name will be listed along with all experiment information.
Search E
Tutorial VII - Launch & Cancel Experiments
Launch Experiment
- launchExperiment.php is used to launch individual experiments.
- Currently with the scripts to launch an experiment user need to pass only the experiment ID as a command line arguments to the script.
- Format;
- php launchExperiment.php<space><experiment_id>
- Upon successful launch a confirmation message will be displayed;
Experiment<space><experiment_id><space>is<space>launched!
Cancel/Terminate the Experiment
- Experiments which are not in statuses COMPLETED, CANCELED, UNKNOWN can be canceled/terminated.
- In order to cancel use;
- Format;
php terminateExperiment.php<space><Experiment ID>
- User provided with the message; 'If there are no exceptions, assume the experiment terminated successfully'
- Experiment will be terminated/canceled. The status can be viewed by using the command getExperimentStatus.php. Status will be immediately changed to CANCELING and then to CANCELED.
Tutorial VIII - Get Experiment Results & Status
Check Experiment Status
- To check the experiment status;
- Format;
php getExperimentStatus.php<space><experiment_id>
- Experiment status will be displayed to the user in the command line.
- experiment status = COMPLETED
Check Experiment Output
- Once the experiment is COMPLETED (Status of the experiment is checked using above getExperimentStatus.php) user can check the output.
- To check the output
- Format;
php getExperimentOutputs.php<space><experiment_id>
Image - Sample output
Tutorial IX - List Applications
List Application Interfaces
- For user to view all existing applications and their deployments in resources can use; getAllApplicationInterfaceNames.php script.
- All the applications used within the gateway will be listed.
- Execute php getAllApplicationInterfaceNames.php
Tutorial X - Airavata API tester
- This special script consist of several API method executions.
- Format;
php airavata-client-api-tester.php<space><username>
- By this single script user can create project, update the project, create experiment, launch experiment, view experiment, clone experiment, etc...
- Explore the script for more infomration and build on this script.
Useful Commands
Action | Command |
---|
Make a directory | mkdir <directory name> |
Navigate to directory | cd <directory name> |
List directory content | ls <directory name> |
Navigate to a directory giving path | cd <..../….../…../ directory name> cd SciGaP/Airavata-PHP-Client-Samples/client-samples |
Check for PHP existence | php –v |
Install PHP & GIT | sudo apt-get install php5-cli sudo apt-get install git |
The given sequence will ensure getting a new copy from git reverting all the local changes have made to the local scripts | git reset --hard HEAD git pull |
...