# Species Editor

The species editor allows you to view and edit the species. The identifier (ID) field is required. In order to be compatible with SBML, there are a couple of restrictions. The identifier is a string that starts with an underscore or a letter and is composed entirely of underscores, letters and digits. Spaces and special characters like $ are not allowed. "s1", "species158", "unstableDimer", and "_pi_314" are all valid identifiers. (Don't enter the quotes.) "2x4", "species 158", "s-158" are invalid. Finally, the identifiers must be unique. The name field is optional. It is an arbitrary string that describes the species, for example "unstable dimer". "Coolest #*@$ species ever!!!" is also a valid name, but show a little restraint - this is science. The compartment field is optional. It does not affect the simulation output. By default the name and compartment fields are hidden. Click in the tool bar to show or hide these columns.

The initial amount field is required. It is the initial population of the species and must evaluate to a non-negative integer. You may enter a number or any Python expression involving the parameters. The following are examples of valid initial amounts.

- `100`
- `1e10`
- `2**10`
- `pow(X0, 3)`
- `ceil(pi * R**2)`

Here we assume that `X0` and `R` have been defined as parameters. `pow` and `ceil` are math functions. `pi` is a mathematical constant.

There is a tool bar for editing the species. You can select rows by clicking on the row label along the left side of the table. The following operations are available:

- Add a species to the table. If you select a row, the new species will be inserted above that row.
- Delete the selected rows.
- Left click to move the selected row up. Right click to move the selected row to the top. This has no effect if no rows or multiple rows are selected.
- Left click to move the selected row down. Right click to move the selected row to the bottom.
- Left click to sort by identifier in ascending order. Right click to sort in descending order.
- Automatically size the cells in the table to fit their contents.
- Show/hide the optional fields.

If the species table is not valid, you will get an error message when you try to launch a simulation.

A Note About Identifiers and Compartments.
Note that in designing a scheme to describe species and compartments one could use either species identifiers that have compartment scope or global scope. We follow the SBML convention that the identifiers have global scope and therefore must be unique. Consider a trivial problem with two species X and Y and two compartments A and B. If species identifiers had compartment scope then one could describe the species as below.

    ID  Compartment
    ---------------
    X   A
    Y   A
    X   B
    Y   B

This notation is handy because we can easily see that although the populations of X in A and B are distinct, they are populations of the same type of species. The disadvantage of this notation is that writing reactions is verbose. One cannot simply write "X → Y", because it does not specify whether the reaction occurs in A, or B, or both. Furthermore a notation such as "X → Y in A" is not sufficient because it cannot describe transport between compartments. Thus, one is stuck with a notation such as "X in A → Y in A." In Cain, the species identifiers must be unique:

    ID    Compartment
    -----------------
    X_A   A
    Y_A   A
    X_B   B
    Y_B   B

Thus the compartment field is optional; it is not used to describe the reactions and does not affect simulation results. It's only use is in visually categorizing the species. If you leave the compartment field blank, then internally each species is placed in the same unnamed compartment. If you export such a model in SBML format, the compartment will be given an identifier such as "Unnamed".