User Defined Functions

COPASI provides a comprehensive library of commonly used kinetic functions that you can choose from when building your model. You can view the complete list of these predefined functions by navigating to the Functions branch of the object tree in the COPASI interface.

Function Table with predefined Functions

Sometimes you may need to define a custom kinetic function to address a specific modeling requirement. COPASI allows you to create your own functions by either double-clicking an empty row in the functions table or clicking the New button at the bottom of the screen. In the function definition dialog, enter a unique name for your new function in the Function Name field. Then, specify the formula that describes the reaction rate in the Formula field.

The allowable syntax allowed for functions is specified in the Available Operators and Functions section below.

Note that this formula should only represent the right-hand side of the rate equation.

Function Definition Dialog

For example, if you want to define the Michaelis-Menten equation, which can be written as v = V * (S / (Km + S)), you would enter only the right-hand side (V * (S / (Km + S))) into the Formula field. As you type, COPASI immediately attempts to interpret the formula and automatically identifies any parameters used. These parameters are then listed in the Parameters table below the formula entry area.

Function Definition Dialog with graphical Display of the Function

In COPASI, parameter names can be chosen freely, but there are a few important rules to keep in mind:

• If a parameter name starts with a letter or underscore, and contains only letters, digits, or underscores, no special formatting is needed.
• If the name contains any other characters, you must enclose the entire name in double quotes.
• If the name itself includes double quotes or backslashes, these characters need to be escaped with a backslash (e.g., \" or \\).

By default, any variable identified in your function formula will be assigned the type Parameter. However, you should specify the correct type for each variable by selecting from the “Description” dropdown list. Valid options are:

• Substrate: for substrates of a reaction,
• Product: for products of a reaction,
• Modifier: a species that is neither produced or consumed
• Parameter: a local or global parameters
• Volumne: a compartment
• Time: the model time symbol

The types you assign to variables will affect where the function can be used. For example, if you define a function using two substrates and a modifier, that function can only be applied to reactions which actually have two substrates and a modifier.

You can also see how restrictions apply in the “Application Restrictions” table, which appears below the Parameters table in the function dialog. For example, if you define a function as A*B and set A and B to be substrates, the Application Restrictions table will indicate that this function is applicable only to reactions with exactly two substrates. After defining such a function, it can be used for any chemical reaction containing exactly two substrates.

Before committing your function, you must also specify whether it is valid for reversible reactions, irreversible reactions, or both. This is controlled using the Reversible, Irreversible, or General radio buttons.

You can also call other functions from within your user-defined function. Keep these four important rules in mind when calling a function from another function:

1. No recursive calls: A function must not call itself, directly or indirectly (i.e., through calling another function which calls the first).
2. Correct number of arguments: Ensure that you provide the exact number of arguments required by the function you’re calling.
3. Correct argument types: Make sure that the types of arguments match what is expected by the function. For example, if calling Henry-Michaelis-Menten (irreversible), the first argument must be a Substrate and the other two must be Parameters.

4. Quoting function names: COPASI’s built-in function names may include spaces or special characters (such as hyphens). To call one of these functions, put its name in double quotes. For instance, you would call it like this:

   "Henry-Michaelis-Menten (irreversible)"(S, Km, V)
   

Once you have created and committed your user-defined function, it becomes available for use in reaction definitions just like any other kinetic rate law.

Available Operators and Functions

The operators and functions that COPASI knows and therefore can be used to create user defined functions are the following:

Standard Operators

Miscellaneaous Functions

Trigonometric Functions

Random Distribuitions

Logical Operators

The logical operators and comparisons are evaluated in the order they are listed in the table.

Conditional Statement

In addition to defining "normal" functions, COPASI allows the definition of piecewise defined functions. Piecewise defined functions are constructed with the IF statement.

The function name for the if statement must be written entirely in lowercase (if) or entirely in uppercase (IF). Mixing uppercase and lowercase letters in the name (e.g., “If” or “iF”) is not allowed and will result in an error.

The if function takes three arguments, separated by commas:

1. Boolean expression — this condition is evaluated first.
2. Expression if true — used if the Boolean expression is true.
3. Expression if false — used if the Boolean expression is false.

To clarify its usage, here’s an example showing how to define the Heaviside step function in COPASI:

if(x lt 0.0, 0.0, if(x gt 0.0, 1.0, 0.5))

In this example, the result is:

• 0.0 if x < 0.0,
• 1.0 if x > 0.0, and
• 0.5 if x == 0.0.

Parenthesis

Built-in Constants

In addition to the function and operators above, COPASI knows some predefined constant names:

Note: Built-in constant names must be written using either all lowercase or all uppercase letters. Mixing uppercase and lowercase letters is not allowed and will result in errors.