# Usage of the PyRolL Command Line Interface

If the `pyroll` package is installed via `pip`, a command line tool name `pyroll` is installed alongside in the system.

> If the tool is not available, please check the content of your `PATH` environment variable.

The tool has the following syntax:

    pyroll [OPTIONS] COMMAND1 [ARGS]... [COMMAND2 [ARGS]...]...

As one can see, subcommands can be chained in one command line. For this reason subcommands take never arguments, but
only options. Commands that rely on the data generated by another command *must* be chained, since no data persists
between different runs of the tool.

At `OPTIONS` several gloabl options can be set, namely:

| Option                  | Description                                                                                                                                |
|-------------------------|--------------------------------------------------------------------------------------------------------------------------------------------|
| `-c, --configfile PATH` | Give a path to a config YAML file. Per default the file `./config.yaml` is used if it exists. See [here](#config-file-format) for details. |
| `-p, --plugin NAME`     | Give a plugin to load additionally to the ones specified in the config. Can be used multiple times.                                        |

The tool provides a set of subcommands explained in [the following section](#commands).

## Commands

### `create-config`

Creates a standard config file with basic logging configuration and empty plugins list. The file is created in the path
specified by the `-f`/`--file` option, which defaults to `./config.yaml`.

### `create-input-py`

Creates a sample input script for use with the [`input-py`](#input-py) command. The file is created in the path
specified by the `-f`/`--file` option, which defaults to `./input.py`. This file can be used as is and modified as
desired. It represents the conditions of the 3-high experimental rolling stand at
the [Institute of Metals Forming](https://tu-freiberg.de/en/fakult5/imf).

### `new`

Creates a new PyRolL simulation project in the directory specified by `-d/--dir`. 
The directory will be created if not already existing.
Creates a `config.yaml` and an `input.py` in the specified directory.
This command is basically a shortcut for 

    pyroll -c <dir>/config.yaml create-config -p -f <dir>/config.yaml create-input-py -k min -f <dir>/input.py 

in a fresh or existing directory.

### `input-py`

Reads input data from the file specified by the `-f`/`--file` option, which defaults to `./input.py`. Use
the [`create-input-py`](#create-input-py) command to create a sample which can be modified.
See [here](#python-input-format) for more information on the format of this file.

### `solve`

Runs the solution procedure for the pass sequence loaded by one of the input commands.

### `report`

Generates a HTML report page from the simulation results. The contents of the page can be extended by plugins, please
see [here](report.md) for additional information. The file to write to can be specified with the `-f`/`--file` option,
which defaults to `report.html`.

## Examples

To read from a python script, solve and generate a report just use:

    pyroll input-py solve report

To specify the files explicitly use:

    pyroll input-py -f input.py solve report -f report.html

To use a different config file:

    pyroll -c config2.yaml input-py solve report

To load additional plugins:

    pyroll -p pyroll_plugin1 -p pyroll_plugin2 input-py solve report

## Config File Format

The configuration has to be specified in YAML format. The content of the default config file is as follows:

```yaml
plugins: [ ] # list full qualified names of plugins to load (as they were importable in real python code)

logging: # configuration for the logging standard library package
  version: 1
  formatters:
    console:
      format: '[%(levelname)s] %(name)s: %(message)s'
    file:
      format: '%(asctime)s [%(levelname)s] %(name)s: %(message)s'

  handlers:
    console:
      class: logging.StreamHandler
      level: INFO
      formatter: console
      stream: ext://sys.stdout
    file:
      class: logging.FileHandler
      level: INFO
      formatter: file
      filename: pyroll.log

  root:
    level: INFO
    handlers: [ console, file ]

  loggers:
    matplotlib:
      level: ERROR
```

In the plugins node several plugins can be specified to load additionally to the core functionalities. List the full
qualified package name you want to load, as you would import in Python. For example to load
the [Wusatowski Spreading](https://github.com/pyroll-project/pyroll-wusatowski-spreading) and
the [Integral Thermal](https://github.com/pyroll-project/pyroll-wusatowski-spreading)
plugins:

```yaml
plugins:
  - pyroll_wusatowski_spreading
  - pyroll_integral_thermal
```

The logging node configures logging using the Python standard `logging` package,
see [here](https://docs.python.org/3/howto/logging.html) for further information on that. The default config specifies
logging on the console and to the `pyroll.log` file on information level. If you want more detailed logging, replace
the `INFO` specifiers with `DEBUG`. To avoid log pollution by the `matplotlib` package, their level is set to `ERROR`.

## Python Input Format

The most flexible way of defining input for PyRolL is the direct use of a python script. A script loadable by
the [`input-py`](#input-py) command must define at least two variables:

| Variable     | Description                                                                                                                                        |
|--------------|----------------------------------------------------------------------------------------------------------------------------------------------------|
| `in_profile` | A [`Profile`](profile.md) object defining the properties of the incoming workpiece.                                                                |
| `sequence`   | A list of [`Unit`](units.md) objects (either [`RollPass`](units.md#roll-passes) or [`Transport`](units.md#transports)) defining the pass sequence. |

A minimal input script is shown below:

```python
from pyroll.core.grooves import SquareGroove, DiamondGroove
from pyroll.core import Profile
from pyroll.core import RollPass
from numpy import pi

# initial profile
in_profile = Profile(
    width=68e-3,
    height=68e-3,
    groove=SquareGroove(r1=0, r2=3e-3, tip_angle=pi / 2, tip_depth=34e-3),
    temperature=1200 + 273.15,
    strain=0,
    material="C45",
    flow_stress=50e6
)

# pass sequence
sequence = [
    RollPass(
        label="Diamond I",
        groove=DiamondGroove(
            usable_width=76.55e-3,
            tip_depth=22.1e-3,
            r1=12e-3,
            r2=8e-3
        ),
        roll_radius=160e-3,
        velocity=1.4,
        gap=3e-3,
    ),
    RollPass(
        label="Square II",
        groove=SquareGroove(
            usable_width=52.7e-3,
            tip_depth=25.95e-3,
            r1=8e-3,
            r2=6e-3
        ),
        roll_radius=160e-3,
        velocity=1.4,
        gap=3e-3,
    ),
]
```

The attributes to give as keyword arguments to the constructors depend on the plugins loaded. Most plugins need
additional data about the pass sequence or the incoming profile. For information on the basic data needed see the docs
of [Profile](profile.md), [RollPass](units.md#roll-passes) and [Transport](units.md#transports).