Apache Airavata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 12 Next »

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

  1. Make sure you have PHP & GIT  installed in your machine.  
    NOTE: The tutorial steps are given for Linux environment.

You Will Learn

  1. Execution of Airavata API methods using PHP client-command line.
  2. How to enter/modify input parameters for the methods in command-line.

Tutorial I - Preparation

  1. Create a folder (ex: SciGaP) in a preferable location in your local machine to clone the PHP samples from GitHub. 
  2. 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. 
  3. 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
  4. client-samples  folder contains PHP scripts to exercise currently existing Airavata API methods;
    1. GetAPIVersion.php (a sanity check)
    2. add-compute-resources.php
    3. createProject.php
    4. updateProject.php
    5. getAllUserProjects.php
    6. createExperiment.php
    7. getExperiment.php
    8. updateExperiment.php
    9. cloneExperiment.php
    10. getAllExperimentsInProject.php
    11. getAllUserExperiments.php
    12. launchExperiment.php
    13. getExperimentStatus.php
    14. getExperimentOutputs.php
    15. terminateExperiment.php
    16. list-application-interfaces.php
    17. list-compute-resources.php
    18. airavata-client-api-tester.php
  5. Apart for the scripts for the API methods the folder contains;
    1. airavata-client-properties.ini - contains the server. port and timeout period information
    2. README-PHP-CLI-Examples.txt - Gives the script execution order
  6. 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

  1. Get Airavata Version 
    Execute php getAPIVersion.php and confirm the Airavata API version.

Tutorial III - Create, Update & List Projects

Create Project
  1. Use; createProject.php to create new projects.
    project_owner and project_name can be given as command line arguments.
    1. Format;
      php createProject.php<space><project_owner><space><project_name>
  2. When creating new projects both project_owner and project_name cannot contain spaces.
    1. Sample values;
      project_owner: Thomas   
      project_name: Test_Project
  3. Successful creation of project will give confirmation message with the Project ID 
    Project<space><project_ID><space>is<space>created! 
  4. Tutorial tryout; 
    Add project description as a command-line argument to the existing createProject.php script and execute.

Update Project
  1. Use; updateProject.php to modify or add project description.
    project_ID and project_description are passed into the script as command line arguments.
    1. Format;
      php updateProject.php<space><project_ID><space><project_description>
  2. When updating Projects currently user can only update the project description. Description cannot contain spaces.
    1. Sample values;
      project_ID: Test_Project_4063b440-332a-49af-a6de-aea21d77bb2f
      project_description: Test_Airavata_Project
  3. Successful modification of project will give confirmation message with the Project ID 
    Project<space><project_id><space>successfully<space>modified.
  4. Tutorial tryout; 
    Add project name as a command-line argument to the existing updateProject.php script and execute.
List Project
  1. Verify the existence of the above created project by using getAllUserProjects.php file 
  2. User = Project owner who creates the Project. User name is given as a command line argument.
    1. Format;
      php getAllUserProjects.php <space><user>
    2. Sample values;
      user: Thomas
  3. Execute the file; all the projects created by the given user will get listed with project information.

Image - Project Detail Listing

Tutorial IV - Create, View , Update & Clone Experiment

Create Experiment
  1. 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.
    1. Format;
      php createExperiment.php<space><username><space><experiment_name><space><project_ID>
  2. 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

    		 
  3. 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

  4. Execute the file; experiment will be created and experiment ID will be generated; ID is the unique value which identifies the experiment in Airavata.
  5. Experiment creation confirmation message;
    Experiment<space><exp_ID><space>created!
View Experiment (Search by Experiment ID)
  1. To search and view above created experiment use getExperiment.php. 
  2. This would list experiment parameters and information about the experiment such as output, number of nodes, status, etc…  
  3. To view the experiment use;
    1. php getExperiment.php
    2. Format:
      php getExperiment.php<space><exp_ID>
  4. All experiment related information will be listed along with experiment ID, experiment name, resource, application , user configuration data, etc…
Update Experiment
  1. To update above created experiment use updateExperiment.php. 
  2. Currently the script modifies only the experiment name, by adding a generated text at the end of the name.  
  3. To modify the experiment use;
    1. php updateExperiment.php
    2. Format:
      php updateExperiment.php<space><exp_ID>
  4. Once executed experiment details will be displayed along with the new experiment name.
  5. Tutorial tryout; 
    1. Modifying the script to update more data in the experiment the same way; Try updating exp_description.  
    2. Update the script to modify existing configuration data by feeding the new values as command line arguments.
Clone Experiment
  1. To clone above modified experiment use cloneExperiment.php.
  2. Cloning will create exact copy of the existing experiment with a new experiment ID in CREATED state. 
  3. To clone the experiment use;
    1. php cloneExperiment.php
    2. Format:
      php cloneExperiment.php<space><exp_ID>
  4. Experiment modification confirmation message;
    1. Experiment<space><exp_ID><space>cloned!
  5. User can clone any experiment created by him/her irrespective of the experiment status.
  6. User can change existing information by updating the newly created experiment.
  7. Tutorial tryout;
    1. Try adding parameters to the script to change other data in the new experiment. E.g.: Exp name, Application, Resource, etc… and execute.

Tutorial V - Search Experiments

Get All Experiments In Project
  1. To view all experiments created under one project we use getAllExperimentsInProject.php.
    1. Format:
      php getAllExperimentsInProject.php<space><project_ID>
  2. All the experiments and their details created using the given project_ID will be listed.
Get All Experiments by User
  1. To view all experiments created by a single user we use getAllUserExperiments.php.
    1. Format:
      php getAllUserExperiments.php<space><username>
  2. All the experiments and their details created by the given user/username will be listed.
Search Experiments by Experiment Name
  1. Experiments can be searched by providing username along with experiment name or part of the experiment name.
    1. Format;
      php search_experiments_by_name.php<space><username><space><experiment_name>
    2. Example;
      php search_experiments_by_name.php Test_User Exp
  2. 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 Experiments by Experiment Description

 

  1. Experiments can be searched by providing username along with experiment description or part of the experiment description.
    1. Format;
      php search_experiments_by_description.php<space><username><space><experiment_description>
    2. Example;
      php search_experiments_by_description.php Test_User Test
  2. When the script is executed; all the experiments which has the given text as part of the description will be listed along with all experiment information.
Search Experiments by Application

 

  1. Experiments can be searched by providing username along with applicationId or part of the applicationId.
    1. Format;
      php search_experiments_by_application.php<space><username><space><applicationID>
    2. Example;
      php search_experiments_by_application.php Test_User Echo
  2. When the script is executed; all the experiments which has the given text as part of the application ID will be listed along with all experiment information.

Tutorial VI - Launch & Cancel Experiments

Launch Experiment
  1. launchExperiment.php is used to launch individual experiments. 
  2. Currently with the scripts to launch an experiment user need to pass only the experiment ID as a command line arguments to the script.
    1. Format;
    2. php launchExperiment.php<space><experiment_id>
  3. Upon successful launch a confirmation message will be displayed; 
    Experiment<space><experiment_id><space>is<space>launched!     
Cancel/Terminate the Experiment
  1. Experiments which are not in statuses COMPLETED, CANCELED, UNKNOWN can be canceled/terminated. 
  2. In order to cancel use;
    1. Format;
      php terminateExperiment.php<space><Experiment ID>
  3. User provided with the message; 'If there are no exceptions, assume the experiment terminated successfully'
  4. 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 VII - Get Experiment Results & Status

  Check Experiment Status
  1. To check the experiment status;
    1. Format; 
      php getExperimentStatus.php<space><experiment_id>
  2. Experiment status will be displayed to the user in the command line.
    1. experiment status = COMPLETED
Check Experiment Output
  1. Once the experiment is COMPLETED (Status of the experiment is checked using above getExperimentStatus.php) user can check the output. 
  2. To check the output  
    1. Format; 
      php getExperimentOutputs.php<space><experiment_id>

 

Image - Sample output

Tutorial VIII - Computational Resources

Register Computational Resource
  1. To add computational resources use script; registerComputeResource.php
  2. In order to run the script hostName and resourceDescription are passed as command line arguments.
    1. Format;
      php registerComputeResource.php<space><hostName><space><resourceDescription>
  3. Execute the above and a confirmation message will be prompted along with the resource ID (computResourceId)
    Compute Resource<space><computeResourceId><space>is<space>registered!
  4. Tutorial Tryout;
    Add other parameters to the script as command line arguments and improve the script.
    1. hostAliases

    2. ipAddresses

Tutorial IX - Application Modules

Register Application Module
  1. To add new application module use the script; registerApplicationModule.php
  2. Parameters appModuleName, appModuleVersion and appModuleDescription are passed as command line arguments to the script.
    1. Format;
      php registerApplicationModule.php<space><appModuleName><space><appModuleVersion><space><appModuleDescription>
  3. Successful execution of the script will display the created application module object along with the confirmation message

  4. Confirmation message contains the application module ID generated at module creation.
    Application Module <appModuleId><space>is<space>registered!

Tutorial X - Application Interfaces

Register Application Interface
  1. To register a new application interface using above created application module use the script; registerApplicationInterface.php
  2. Along with application interface name and description also need to provide application module ID as  command line arguments to the script.
    1. Format;
      php registerApplicationInterface.php<space><appName><space><appDescription><space><appModuleId>
  3. Successful execution of the script will display the created application interface object along with the confirmation message

  4. Confirmation message contains the application interface ID generated at creation.
    Application Interface <applicationInterfaceId><space>is<space>registered!
Update Application Interface
  1. Use script updateApplicationInterface.php to update the above registered application interface.
    1. Format;
      php updateApplicationInterface.php<space><appInterfaceId>
  2. Execution of the script will update name of the application input and application output.

  3. Confirmation message contains the application interface ID generated at update.
    Application Interface <applicationInterfaceId><space>is<space>updated!
Delete Application Interface
  1. User can delete existing application interface by providing the application interface ID as a command line argument to the script; deleteApplicationInterface.php
    1. Format;
      php deleteApplicationInterface.php<space><appInterfaceId>
  2. At sucesful execution a confirmation message will be prompted to coinfrm the deletion
    Application Interface <applicationInterfaceId><space>successfully<space>deleted

Tutorial IX - List Applications

List Application Interfaces
  1. For user to view all existing applications and their deployments in resources can use; getAllApplicationInterfaceNames.php script.
  2. All the applications used within the gateway will be listed. 
  3. Execute php getAllApplicationInterfaceNames.php

Tutorial X - Airavata API tester

  1. This special script consist of several API method executions. 
    1. Format;
      php airavata-client-api-tester.php<space><username>
  2. By this single script user can create project, update the project, create experiment, launch experiment, view experiment, clone experiment, etc... 
  3. 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

 














    


 

  • No labels

For an overview of Apache Airavata visit the Website - https://airavata.apache.org/