Usage of the PyRolL Command Line Interface

If the pyroll-cli package is installed via pip, a command line tool named pyroll is installed 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 global options can be set, namely:

Option	Description
`-c, --configfile PATH`	Give a path to a config TOML file. Per default the file `./config.toml` is used if it exists. See here 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

`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.toml.

`create-input-py`

Creates a sample input script for use with the 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.

`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.toml and an input.py in the specified directory. This command is basically a shortcut for

pyroll -c <dir>/config.toml create-config -p -f <dir>/config.toml 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 command to create a sample which can be modified. See here 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.

Examples

To read from a python script, solve and generate a report just use (needs the pyroll-report package):

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.toml input-py solve report

To load additional plugins:

pyroll -p pyroll.plugin1 -p pyroll.plugin2 input-py solve report

Plugins can also be loaded by the config file or by importing them directly in the input file.

Config File Format

The configuration has to be specified in TOML format. PyRolL looks for two config files and merges them: first the global config file in the app config directory (f.e. in ~/.config/pyroll on Linux or %APPDATA%\pyroll on Windows) and second in the local working directory. The local file always overrides the global config. If the global config does not exist, the CLI creates it automatically at the first run. The content of the default config file is as follows:

[pyroll]

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

# set config values of a respective package
[pyroll.core]
ROLL_PASS_AUTO_ROTATION = true
GROOVE_PADDING = 0.2
DEFAULT_MAX_ITERATION_COUNT = 100
DEFAULT_ITERATION_PRECISION = 1e-2
ROLL_SURFACE_DISCRETIZATION_COUNT = 100

[logging] # configuration for the logging standard library package
version = 1

formatters.console.format = '[%(levelname)s] %(name)s: %(message)s'
formatters.file.format = '%(asctime)s [%(levelname)s] %(name)s: %(message)s'

[logging.handlers.console]

class = "logging.StreamHandler"
level = "INFO"
formatter = "console"
stream = "ext://sys.stdout"

[logging.handlers.file]
class = "logging.FileHandler"
level = "DEBUG"
formatter = "file"
filename = "pyroll.log"

[logging.root]
level = "WARNING"
handlers = ["console", "file"]

[logging.loggers.pyroll]
level = "DEBUG"

In the plugins array 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, or, if the package resides in the pyroll namespace as per convention, the name of the subpackage. For example to load the Wusatowski Spreading and the Integral Thermal plugins:

plugins = [
    "pyroll.wusatowski_spreading", # with full package name
    "integral_thermal", # assume pyroll.-prefix implicitly
]

The logging section configures logging using the Python standard logging package, see here 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 command must define at least two variables:

Variable	Description
`in_profile`	An instance of `Profile` object defining the properties of the incoming workpiece.
`sequence`	An instance of `PassSequence` defining the processing steps.

A minimal input script is shown below:

import pyroll.core as pr

# initial profile
in_profile = pr.Profile.round(
    diameter=30e-3,
    temperature=1200 + 273.15,
    strain=0,
    material=["C45", "steel"],
    flow_stress=100e6
)

# pass sequence
sequence = pr.PassSequence([
    pr.RollPass(
        label="Oval I",
        roll=pr.Roll(
            groove=pr.CircularOvalGroove(
                depth=8e-3,
                r1=6e-3,
                r2=40e-3
            ),
            nominal_radius=160e-3,
            rotational_frequency=1
        ),
        gap=2e-3,
    ),
    pr.Transport(
        label="I => II",
        duration=1
    ),
    pr.RollPass(
        label="Round II",
        roll=pr.Roll(
            groove=pr.RoundGroove(
                r1=1e-3,
                r2=12.5e-3,
                depth=11.5e-3
            ),
            nominal_radius=160e-3,
            rotational_frequency=1
        ),
        gap=2e-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.

Shell Tab Completion

To configure tab completion for common shells execute one of the following commands.

`bash`

_PYROLL_COMPLETE=bash_source >> ~/.bashrc

`zsh`

_PYROLL_COMPLETE=zsh_source >> ~/.zshrc

`fish`

_PYROLL_COMPLETE=fish_source >> ~/.config/fish/completions/pyroll.fish

Usage of the PyRolL Command Line Interface

Commands

create-config

create-input-py

new

input-py

solve