Help Resources PIFOP Usage Getting Started Running a Solver Collaboration and Sharing Options Supported Languages and Files Working with Google Sheets Markdown + LaTeX Project Answer Project Collections List of Examples Provisioned Optimization Server Enterprise Plan and Subscription Keys Hosting an Optimization Server Introduction to Optimization Server Hosting Hosting an Opt-Server Configure Commands Basic Command Configurations Security Best Practices Manage Users List of Configuration Options PIFOP FUNCTIONS Introduction to PIFOP Functions Create and Manage PIFOP Functions PIFOP Functions REST API AMPL Basics Program Structure Model Entities Set Expressions Indexing Expressions Data Assignment Basic Commands More AMPL References Attributes of Sets, Parameters and Variables Printing Commands and Options

Create and Manage PIFOP Functions

PIFOP Functions is an experimental feature. Contact us if you would like to try it out.

Prerequisites

In order to create a PIFOP Function, you will need:

1. A PIFOP subscription plan with PIFOP Functions enabled. At the present stage of development, PIFOP Functions is not enabled by default in any of our plans. Contact us if you are interested in trying it out.
2. An Optimization Server — where the Function will be deployed to.

Create or open the project that you want to deploy

A PIFOP Function — or just Function — is essentially a deployment of a PIFOP project. You can think of a Function as a snapshot of a project and a command line to be executed. The snapshot will be stored in an optimization server. When the Function is called, the snapshot is loaded and the command line is executed.

In order to create a Function, the first thing that you will need is to create or open a project that you want to deploy. You don't need a special kind of project. Any project can be deployed as a Function: an AMPL or GAMS model, a Python heuristic, a C/C++ program, etc.

Function input and output

The communication between the caller of a Function and the Function itself is done via files: the caller feeds the Function with one or more input files and gets back one or more output files. You should implement your model/program in such a way that the caller's input is read from one or more files, which will be created/overwritten when the Function snapshot is loaded for execution.

Likewise, the Function output should be written to one or more files that the caller will be able to download after the execution is finished.

To keep things simple, we recommend that you design your optimization program to read the input from a single input file if possible, and that you write the results into a single output file in a portable format, such as JSON and CSV.

The definition of which files can be written (or overwritten) by the caller is made using the input property of the Function configuration file. More on that below.

Create configuration file

Once you are ready to deploy your project as a Function, create a func.json configuration file to describe the Function that you are deploying. This file should contain all the necessary information for running the Function, such as its id, the id and path of the input files and the command line that will be executed when the Function is called.

See below the list of Function properties that can be set in the configuration file.

Property Description "id"REQUIRED STRING The id of the Function. Must an alpha-numeric string that is unique across all your Functions. "command"REQUIRED STRING The command line that is executed when this Function is called. "name"STRING The name of the Function. "description"STRING The description of the Function. What does it do? "input"ARRAY OF OBJECTS List of objects describing the input files that users of this Function can submit. Each entry can have the following properties:

• "id" — required alpha-numeric string identifying this input.
• "path" — required file path where the input will be written to — or which file should be overwritten.
• "description" — description of the file.

"output"ARRAY OF OBJECTS List of objects describing the output files that users of this Function can try to download after the execution is finished. Each entry can have the following properties:

• "id" — required alpha-numeric string identifying this output.
• "path" — required file path where the output will be written to — or which file should be overwritten.
• "description" — description of the file.

Deploy Function

1. After creating the Function configuration file, Select the Optimization Server where you want the Function to be deployed to. The selected Optimization Server is where the project snapshot will be stored and where the Function will be executed when called. You should have already tested your program in the selected Opt-Server to make sure it is properly configured to execute the Function command line.
2. Enter the following command line into the terminal:

   > function create --config func.json

3. Upon success, this command creates a PIFOP Function with the specifications in func.json, and you will receive an API and a Master key, about which you can learn more below.

Test Function

You can test if your Function is working properly using the function execute terminal command.

1. Create the input file(s) with which you want to test the Function.
2. Enter the command below into a terminal. Modify the highlighted parts accordingly.

   > function execute func_uid --input:input_id input_path --output:output_id output_path --apikey apikey

   • func_uid — the UID or id of the Function. The UID takes the form author/id, where author is your username and id is the id of the Function. If only the Function id entered, the author is assumed to be your username.
   • --input:... and --output:... — use these options followed by the input/output id and path to submit/retrieve input/output file(s). You can enter multiple input files and retrieve multiple output files. Example:

     --input:input1 input_path1 --input:input2 input_path2 --output:output1 output_path1 --output:output2 output_path2

   • apikey — Function API key.
3. If the execution is successful, the output file(s) will be created in the path(s) that you've specified.

API and Master keys

Generally speaking, programatic interations with PIFOP Functions require either an API or a Master key.

• API keys are for actually executing the Function, and they start with apikey. Anyone with a Function API key can execute it. Multiple API keys can exist for any given Function. The author of the Function is responsible for generating and managing the Function API keys. Learn more about Function management below.
• Master keys are for administrative operations, such as generating and deleting API keys, and they start with master. Each Function has only one Master key, which is generated when the Function is created.

Should API keys be kept secretly?

It depends on how the Function will be used. For instance, if the Function is supposed to be used in a web application that is publicly available and called from the user's browser — example here — the API key doesn't have to be kept secretly, nor is is possible, since the API key will be available in the client side. But if the Function is supposed to be called only by specific people — e.g. your client(s) — their API key(s) should be kept secretly by you and by them.

If you are developing a Function that will be publicly available for anyone to use, we strongly recommend that you set usage limits to the API key(s) that you share with your users.

The Master key, on the other hand, should always be kept secretly and should not be shared with anyone that is not supposed to have admin rights over the Function.

Update a Function

Virtually any file contained in the Function snapshot and any of its configurations can be updated after its creation — except its id. To do so:

1. Make whatever file changes that you want to do in the Function's project, including in its configuration file.
2. When you are ready, Select an Optimization Server to deploy the Function to — it can be different from the Opt-Server where the Function is currently deployed at.
3. Use the command below to overwrite the current Function with the changes that you've made.

   > function update --config func.json

When you update a Function, all of the Function API and Master keys are preserved.

Manage a Function

Generate API key

1. Go to the Functions management page.
2. Select a Function from the list.
3. Under API Keys, Click on New.
4. Give the new key a unique name and set usage limits to it.
5. Click on Create.
6. Share the generated key with whomever you have generated it for.

Delete API keys

1. Go to the Functions management page.
2. Select a Function from the list.
3. Under API Keys, use the checkboxes on the left to Select the key(s) that you want to delete.
4. Click on the Delete button on the top right and confirm your intention.

Delete Function

1. Go to the Functions management page.
2. Select a Function from the list.
3. Click on the Delete button on the top right and confirm your intention.

Use Function

Use one of our APIs to call the Function from other applications.

• PIFOP Functions REST API
• Introduction to PIFOP Functions