API Reference
lean optimize
Description
Runs a local optimization in a Docker container using the quantconnect/lean Docker image.
The logs of the optimizer are shown in real-time and the full results of the optimizer and all executed backtests are stored in the <project> / optimizations / <timestamp> directory.
You can use the --output
option to change the output directory.
The given <project>
argument must be either a project directory or a file containing the algorithm to optimize.
If it is a project directory, the CLI looks for a main.py or Main.cs file, assuming the first file it finds to contain the algorithm to optimize.
By default, an interactive wizard is shown letting you configure the optimizer.
When --optimizer-config
or --strategy
is given, the command runs in non-interactive mode and doesn't prompt for input.
When the --optimizer-config <config file>
option is given, the specified config file is used.
This option must point to a file containing a full optimizer config (the algorithm-type-name
, algorithm-language
and algorithm-location
properties may be omitted).
See the Optimizer.Launcher / config.example.json file in the LEAN repository for an example optimizer configuration file, which also contains documentation on all the required properties.
When --strategy
is given, the optimizer configuration is read from the command-line options.
This means the --strategy
, --target
, --target-direction
, and --parameter
options become required.
Additionally, you can also use --constraint
to specify optimization constraints.
In non-interactive mode, the parameters can be configured using the --parameter
option.
This option takes the following values: the name of the parameter, its minimum value, its maximum value, and its step size.
You can provide this option multiple times to configure multiple parameters.
In non-interactive mode, the constraints can be configured using the --constraint
option.
This option takes a "statistic operator value" string as value, where the statistic must be a path to a property in a backtest's output file, like "TotalPerformance.PortfolioStatistics.SharpeRatio".
This statistic can also be shortened to "SharpeRatio" or "Sharpe Ratio", in which case the command automatically converts it to the longer version.
The value must be a number and the operator must be <
, >
, <=
, >=
, ==
, or ==
.
You can provide this option multiple times to configure multiple constraints.
Example non-interactive usage:
$ lean optimize "My Project" \ --strategy "Grid Search" \ --target "Sharpe Ratio" \ --target-direction "max" \ --parameter my-first-parameter 1 10 0.5 \ --parameter my-second-parameter 20 30 5 \ --constraint "Drawdown < 0.5" \ --constraint "Sharpe Ratio >= 1"
To estimate the cost of running an optimization job without actually running it, add the --estimate
option to the command. You need to backtest the project at least once in order to estimate the cost of optimizing it.
To set the maximum number of concurrent backtests to run, use the --max-concurrent-backtests
option.
The Docker image that's used contains the same libraries as the ones available on QuantConnect. If the selected project is a C# project, it is compiled before starting the optimization.
By default, the official LEAN engine image is used.
You can override this using the --image <value>
option.
Alternatively, you can set the default engine image for all commands using lean config set engine-image <value>
.
The image is pulled before running the optimizer if it doesn't exist locally yet or if you pass the --update
flag.
Options
The lean optimize
command supports the following options:
Option | Description |
---|---|
--output <path> | Directory to store results in (defaults to <project> / optimizations / <timestamp>). |
--detach , -d | Run the optimization in a detached Docker container and return immediately. The name of the Docker container is shown before the command ends. You can use Docker's own commands to manage the detached container. |
--optimizer-config <path> | The optimizer configuration file that should be used (the algorithm-type-name , algorithm-language and algorithm-location properties may be omitted). See the Optimizer.Launcher / config.example.json file in the LEAN repository for an example optimizer config file. |
--strategy <value> | The optimization strategy to use in non-interactive mode. Must be Grid Search or Euler Search . |
--target <value> | The path to the property in the backtest's output file to target, like "TotalPerformance.PortfolioStatistics.SharpeRatio". May also be a shortened version, like "SharpeRatio" or "Sharpe Ratio". |
--target-direction <value> | min if the target must be minimized, max if it must be maximized. |
--parameter <name> <min> <max> <step> | The 'parameter min max step' pairs configuring the parameters to optimize. May be used multiple times. |
--constraint <value> | The 'statistic operator value' pairs configuring the constraints of the optimization. May be used multiple times. |
--estimate | Estimate optimization runtime without running it. |
--max-concurrent-backtests <value> | Maximum number of concurrent backtests to run (x >= 1). |
--image <value> | The LEAN engine image to use (defaults to quantconnect/lean:latest ). |
--update | Pull the LEAN engine image before running the optimizer. |
--no-update | Use the local LEAN engine image instead of pulling the latest version. |
--lean-config <path> | The Lean configuration file that should be used (defaults to the nearest lean.json file). |
--release | Compile C# projects in release configuration instead of debug. |
--verbose | Enable debug logging. |
--help | Display the help text of the lean optimize command and exit. |