User Guide¶

This documentation covers installing MPilot, the process of creating and running MPilot models, and the process of using the mpilot command-line program. It also includes a reference of all built-in MPilot commands, including the EEMS commands, used to created fuzzy logic models.

Installing MPilot¶

MPilot requires the Python programming language. You will also need a program called Pip, which comes installed with all newer versions of Python. If you have an old version of Python, you may need to install Pip separately.

Once you have Python and Pip, you can install MPilot by running the following command:

pip install mpilot

If you plan to use NetCDF data in your MPilot models, you should install the NetCDF extra:

pip install mpilot[netcdf]

Note

Installing MPilot with NetCDF will require the NetCDF C library to already be installed on your computer. Installing the NetCDF C library is out of the scope of this document, but you can find more information about doing this in the NetCDF documentation.

A Quick Example¶

This example will help you understand the basics of creating and MPilot command file and running it using the mpilot command. In this example, we’ll read two variables from a CSV file, apply a Fuzzy Union, and write the result to a new CSV file. First, create a CSV file called input.csv with two columns, A and B:

A,B
10,5
8,2
7,3
5,10
2,8

When this data is loaded by MPilot, each column will be treated as a list of number. In other words:

A = [10, 8, 7, 5, 1]
B = [5, 2, 3, 10, 8]

Now, create the command file, called model.mpt:

# Read A
A = EEMSRead(
  InFileName = "input.csv",
  InFieldName = "A",
  DataType = "Integer"
)

# Read B
B = EEMSRead(
  InFileName = "input.csv",
  InFieldName = "B",
  DataType = "Integer"
)

# Convert A and B to fuzzy
A_Fz = CvtToFuzzy(
  InFieldName = A,
  TrueThreshold = 10,
  FalseThreshold = 2
)
B_Fz = CvtToFuzzy(
  InFieldName = B,
  TrueThreshold = 10,
  FalseThreshold = 2
)

# Combine A and B with fuzzy union
Union = FuzzyUnion(
  InFieldNames = [A_Fz, B_Fz]
)

# Write A, B, and the union to a new CSV
Out = EEMSWrite(
  OutFileName = "output.csv",
  OutFieldNames = [A, B, Union]
)

This model loads A and B, and converts each array to fuzzy space, i.e., normalized values to between -1 to +1. The TrueThreshold and FalseThreshold parameters determine how this conversion is done. In this case, 10 will become 1 and 2 will become -1. Values between 2 and 10 will be interpolated to values between -1 and 1. The FuzzyUnion command produces the mean of the fuzzy values.

Now we can run this model with:

mpilot eems-csv model.mpt

This should run quickly, and produce a new file, output.csv, which will contain the two input columns, A and B, as well as the result column, Union.

The `mpilot` program¶

mpilot is the command-line program used to run models. It is run with the library to use, and the path to the command file (model):

mpilot <library> <command file>

The library can be either eems-csv to use EEMS commands intended for use with CSV data, or eems-netcdf to use EEMS commands intended for use with NetCDF data. Run mpilot --help for a full list of options.

Command File Syntax¶

MPilot models are expressed using the .mpt command file syntax. These files are easy to write and to understand. They consist of all the commands that make up the model.

Each command follows the same structure:

<result> = <command name>(
  <parameters>
)

Parameters are different for each command and may require a specific type of data (e.g., a number, or an output from a previous command). Each parameter takes the form of <parameter> = <value>, and multiple parameters are separated by commas.

Parameter Types¶

These are the parameter types that may be used by MPilot commands.

String¶

String parameters may be surrounded by quotes, or not. Strings not surrounded by quotes may not contain the following characters: #:,=-+()[]:

# With quotes
Param = "This is a string."

# Without quotes
Param = This is a string.

Number¶

Numbers may be integer of decimal values:

# Integer
Param = 12

# Decimal
Param = 5.4

Boolean¶

A boolean parameter may be true or false:

Param = true
Param = false

Path¶

A path parameter is the same as a string, but must refer to a valid path. For some commands, the path must already exist (e.g., a read command) while for others it will be created (e.g., a write command):

Param = "C:\path\to\file.csv"

Result¶

A result parameter refers to the output of another command:

A = CommandA()
Out = Write(ResultParam = A)

List¶

A list parameter contains any number of values of a specific type. For example, a list of strings, a list of numbers, or a list of results:

Param = [1, 2, 3, 4]

Tuple¶

A tuple parameter is similar to a list, but consists of any number of key/value pairs. Both the key and value are strings, and are separated by a colon ::

Param = [Color:"Blue"]

Data Type¶

One of several possible data types, such as “Float” or “Integer”, determined by the command:

Param = Float

Built-In Command Libraries¶

MPilot includes built-in commands, currently limited to those used for creating EEMS models. A full reference of built-in commands is at MPilot Libraries Reference.