# Create a custom box
To create a functionnal process box for Muphyn application 

Build two files:
- a model description file ;
- a process file.

The two files must have the same basefilename : 
- model description file: `myFile`.yaml
- process file: `myFile`.py

- [Create a custom box](#create-a-custom-box)
  - [1. Model description file (.yaml file)](#1-model-description-file-yaml-file)
    - [1.1. Metadata - General Box Informations](#11-metadata---general-box-informations)
      - [*Box name*](#box-name)
      - [*Box library*](#box-library)
      - [*Box version*](#box-version)
      - [*Box creator*](#box-creator)
      - [*Box icon*](#box-icon)
      - [*Box creation date*](#box-creation-date)
      - [*Box type*](#box-type)
      - [*Box init function*](#box-init-function)
      - [*Box simulation function*](#box-simulation-function)
      - [*Box end function*](#box-end-function)
      - [*Box "wait for event" parameter*](#box-wait-for-event-parameter)
      - [*Box "wait for all signal events" parameter*](#box-wait-for-all-signal-events-parameter)
    - [1.2. Box parameters](#12-box-parameters)
      - [*Inputs groups*](#inputs-groups)
      - [*Outputs groups*](#outputs-groups)
      - [*Parameters*](#parameters)
  - [2. Process file (.py file)](#2-process-file-py-file)
    - [2.1. box\_init\_method](#21-box_init_method)
    - [2.2. box\_function](#22-box_function)
    - [2.3. box\_end\_method](#23-box_end_method)

## 1. Model description file (.yaml file)
The `.yaml` file must contains all these following parameters. For now there is no default value for these parameters 

### 1.1. Metadata - General Box Informations

#### *Box name*
```yaml
name: Name of the box
```

#### *Box library*
This parameter is the library of the box. This parameter must be two words separated by a "." and the first word must be "Boxes": 
```yaml
library: Boxes.libraryName
```

#### *Box version*
```yaml
version: 1.0
```

#### *Box creator*
Name of the box creator
```yaml
creator: FirstName LastName
```

#### *Box icon*
Path to the box icon image file. The image file can be a matrix image file like `.jpg` or `.png` and vector image file like `.svg`
```yaml
icon: Path/To/Image/file.jpg
```

#### *Box creation date*
Box creation date
```yaml
date_creation: YYYY-MM-DD
```

#### *Box type*
Box type must be `code`
```yaml
type: code
```

#### *Box init function*
Name of the initialization simulation function in the process file. If no init function in the process file this paramter mus tbe set to `None`.
```yaml
box_init_method: _init_simulation
```

#### *Box simulation function*
Name of the function called at each step during the simulation in the process file. If no simulation function in the process file this paramter mus tbe set to `None`.
```yaml
box_function: _step_simumation
```

#### *Box end function*
Name of the ending simulation function in the process file. If no ending function in the process file this paramter mus tbe set to `None`.
```yaml
box_end_method: _finish_simulation
```

#### *Box "wait for event" parameter*
This parameter can be set to `False` or `True`. If the box can generate its own value and return it to the output this parameter must be set to `False` like in the case of a source box. If a box must get data form its inputs to generate data for its outputs this parameter must be set to `True`.
```yaml
wait_for_events: True
```

#### *Box "wait for all signal events" parameter*
This parameter must be set to `True`.
```yaml
wait_for_all_signal_events: True
```

### 1.2. Box parameters

#### *Inputs groups*
The `inputs` parameter let us declare multiple inputs groups. Each inputs group must have a `name`, `type` & `isInfinite` value. If the `isInfinite` value is set to `False` the `count` value must be set.
```yaml
inputs:
    - name: Inputs Group 1
      type: float
      isInfinite: True # default count value = 2
      minimumCount: 0
      maximumCount: 5
      count: 1
    - name: Inputs Group 2
      type: float
      isInfinite: False # default count value = 2
      count: 2
```

#### *Outputs groups*
The `outputs` parameter let us declare multiple inputs groups. Each inputs group must have a `name`, `type` & `isInfinite` value. If the `isInfinite` value is set to `False` the `count` value must be set.
```yaml
outputs:
    - name: Outputs Group 1
      type: float
      isInfinite: True # default count value = 2
      minimumCount: 0
      maximumCount: 5
      count: 1
    - name: Outputs Group 2
      type: float
      isInfinite: False # default count value = 2
      count: 2
```

#### *Parameters*
List of all parameters. For now there are the following supported types:
- `string`: text. We can add the `maxLength` parameter which limit the number of characters in the string.
- `int`: integer value. There are `min` & `max` parameter which allows to create range to respect for the integer value.
- `float`: floating value. There are `min` & `max` parameter which allows to create range to respect for the float value.
- `boolean`: boolean value.
- `anyFile`: any file path value. This parameter allows to select an existing or not file (ex: it can be used in the case of selecting the path where to save the file).
- `directory`: directory path value. Existing folder can be selected.
- `existingFile`: existing file path value. Only one existing file can be selected.
- `existingFiles`:  multiple exisiting file path value. Multiple existing files can be selected.

Each parameter can active a function when the parameter value has been changed. This function take one parameter: 
- box_model: `BoxModel`

```yaml
params:
    String property: 
        type: string
        value: ""
        maxLength: 10
    Integer property: 
        type: int
        value: 1234567890
        min: 0
        max: 100
    Float property: 
        type: float
        value: 12345.67890
        min: 0.0
        max: 100.0
    Boolean property: 
        type: boolean
        value: False
    Any File property: 
        type: anyFile
        value: ""
    Directory property: 
        type: directory
        value: ""
    Existing File property: 
        type: existingFile
        value: ""
    Existing Files property: 
        type: existingFiles
        value: ""
```

### 1.3 Full YAML file example
```yaml
box:
  name: BoxName
  library: Library.Path
  version: 1.0
  creator: Firstname Lastname
  date_creation: YYYY-MM-DD
  description: Description
  icon: "Path/To/Image/File"
  type: code
  box_init_method: None
  box_function: name_of_function
  box_end_method: None
  wait_for_events: True
  wait_for_all_signal_events: True

  inputs: 
    - name: Term
      type: float
      isInfinite: True # default count value = 2

  outputs: 
    - name: Sum
      type: float
      value: 0.0
      count: 1
     
  params: None
```

## 2. Process file (.py file)
The process file is a classical Python script file in which we can declare three functions:
- `box_init_method`
- `box_function`
- `box_end_method`

### 2.1. box_init_method
Function that is activated before starting the simulation. This function has two parameters: 
- box: `Box`
- simulation_params: `SchedulerParams`

### 2.2. box_function
Function that is activated at each step of the simulation. This function has two parameters: 
- box: `Box`
- simulation_params: `SchedulerParams`

### 2.3. box_end_method
Function that is activated after the simulation. This function has one parameter: 
- box: `Box`
