Optimize API Reference

The Optimize API allows Quantopian users to describe their desired orders in terms of high-level Objectives and Constraints.

Quick Reference

Entry Points

quantopian.algorithm.order_optimal_portfolio Calculate an optimal portfolio and place orders toward that portfolio.
quantopian.optimize.calculate_optimal_portfolio Calculate new optimal portfolio weights, raising an error on failure.
quantopian.optimize.run_optimization Calculate new optimal portfolio weights.

Note

NOTE: Like other functions in quantopian.algorithm, order_optimal_portfolio() can only be used in trading algorithms.

Objectives

quantopian.optimize.Objective Base class for objectives.
quantopian.optimize.TargetWeights(weights) Objective that minimizes the distance from an already-computed portfolio.
quantopian.optimize.MaximizeAlpha(alphas) Objective that maximizes weights.dot(alphas) for an alpha vector.

Constraints

quantopian.optimize.Constraint Base class for constraints.
quantopian.optimize.MaxGrossExposure(max) Constraint on the maximum gross exposure for the portfolio.
quantopian.optimize.NetExposure(min, max) Constraint on the net exposure of the portfolio.
quantopian.optimize.DollarNeutral([tolerance]) Constraint requiring that long and short exposures must be equal-sized.
quantopian.optimize.NetGroupExposure(labels, ...) Constraint requiring bounded net exposure to groups of assets.
quantopian.optimize.PositionConcentration(...) Constraint enforcing minimum/maximum position weights.
quantopian.optimize.FactorExposure(loadings, ...) Constraint requiring bounded net exposure to a set of risk factors.
quantopian.optimize.Pair(long, short[, ...]) A constraint representing a pair of inverse-weighted stocks.
quantopian.optimize.Basket(assets, ...) Constraint requiring bounded net exposure to a basket of stocks.
quantopian.optimize.Frozen(asset_or_assets) Constraint for assets whose positions cannot change.
quantopian.optimize.ReduceOnly(asset_or_assets) Constraint for assets whose weights can only move toward zero and cannot cross zero.
quantopian.optimize.LongOnly(asset_or_assets) Constraint for assets that cannot be held in short positions.
quantopian.optimize.ShortOnly(asset_or_assets) Constraint for assets that cannot be held in long positions.
quantopian.optimize.FixedWeight(asset, weight) A constraint representing an asset whose position weight is fixed as a specified value.
quantopian.optimize.CannotHold(asset_or_assets) Constraint for assets whose position sizes must be 0.
quantopian.optimize.experimental.RiskModelExposure(...) Constraint requiring bounded net exposure to the set of risk factors provided by the Quantopian Risk Model.

Results and Errors

quantopian.optimize.OptimizationResult The result of an optimization.
quantopian.optimize.Diagnostics Diagnostic information about an optimization.
quantopian.optimize.InfeasibleConstraints Raised when an optimization fails because there are no valid portfolios.
quantopian.optimize.UnboundedObjective Raised when an optimization fails because at least one weight in the 'optimal' portfolio is 'infinity'.
quantopian.optimize.OptimizationFailed Generic exception raised when an optimization fails a reason with no special metadata.

Detailed Reference

Entrypoints

quantopian.algorithm.order_optimal_portfolio(objective, constraints)

Calculate an optimal portfolio and place orders toward that portfolio.

Parameters:
Raises:
  • InfeasibleConstraints -- Raised when there is no possible portfolio that satisfies the received constraints.
  • UnboundedObjective -- Raised when the received constraints are not sufficient to put an upper (or lower) bound on the calculated portfolio weights.
Returns:

order_ids -- The unique identifiers for the orders that were placed.

Return type:

pd.Series[zipline.assets.Asset, str]

Notes

This is the only method of ordering allowed in the Quantopian Contest.

quantopian.optimize.calculate_optimal_portfolio(objective, constraints, current_portfolio=None)

Calculate new optimal portfolio weights, raising an error on failure.

Parameters:
  • objective (Objective) -- The objective to be minimized or maximized.
  • constraints (list[Constraint]) -- List of constraints that must be satisfied by the new portfolio.
  • current_portfolio (pd.Series, optional) --

    A Series containing the current portfolio weights, expressed as percentages of the portfolio's liquidation value.

    When called from a trading algorithm, the default value of current_portfolio is the algorithm's current portfolio.

    When called interactively, the default value of current_portfolio is an empty portfolio.

Returns:

optimal_portfolio -- A Series containing portfolio weights that maximize (or minimize) objective without violating any constraints. Weights should be interpreted in the same way as current_portfolio.

Return type:

pd.Series

Raises:
  • InfeasibleConstraints -- Raised when there is no possible portfolio that satisfies the received constraints.
  • UnboundedObjective -- Raised when the received constraints are not sufficient to put an upper (or lower) bound on the calculated portfolio weights.

Notes

This function is a shorthand for calling run_optimization(), checking for an error, and extracting the result's new_weights attribute.

If an optimization problem is feasible, the following are equivalent:

# Using calculate_optimal_portfolio.
weights = calculate_optimal_portfolio(objective, constraints, portfolio)
# Using run_optimization.
result = run_optimization(objective, constraints, portfolio)
result.raise_for_status()  # Raises if the optimization failed.
weights = result.new_weights
quantopian.optimize.run_optimization(objective, constraints, current_portfolio=None)

Calculate new optimal portfolio weights.

Parameters:
  • objective (Objective) -- The objective to be minimized or maximized.
  • constraints (list[Constraint]) -- List of constraints that must be satisfied by the new portfolio.
  • current_portfolio (pd.Series, optional) --

    A Series containing the current portfolio weights, expressed as percentages of the portfolio's liquidation value.

    When called from a trading algorithm, the default value of current_portfolio is the algorithm's current portfolio.

    When called interactively, the default value of current_portfolio is an empty portfolio.

Returns:

result -- An object containing information about the result of the optimization.

Return type:

quantopian.optimize.OptimizationResult

Objectives

class quantopian.optimize.Objective

Base class for objectives.

class quantopian.optimize.TargetWeights(weights)

Objective that minimizes the distance from an already-computed portfolio.

Parameters:weights (pd.Series or dict) -- Map from asset to target percentage of holdings.

Notes

This objective finds new portfolio weights by finding a w_new that minimizes the cost function:

sum((w_new - w_target) ** 2)

where w_target is the provided target weights.

The cost function is minimized globally when w_new == w_target, so this objective will simply produce w_target if w_target satisfies all optimization constraints.

If w_target violates one or more constraints, this objective will find the feasible portfolio closest to w_target by the metric above.

A target weight of 1.0 indicates that 100% of the portfolio's current net liquidation value should be held in a long position.

A target weight of -1.0 indicates that -100% of the portfolio's current net liquidation value should be held in a short position.

Target weights very close to 0.0 are treated specially: they are assumed to express intent to exit an existing position. The objective will attempt to avoid holding these positions unless doing so would require violating constraints.

If an algorithm has an existing position in an asset and no target weight is provided, the target weight is assumed to be zero.

classmethod equal_weight(assets, target_leverage=1.0, **kwargs)

Helper method for constructing a equal-weight target portfolio.

Parameters:
  • assets (iterable[Asset]) -- The assets from which to construct the portfolio.
  • target_leverage (float, optional) -- The target leverage for the portfolio. Each asset in the resulting portfolio will be weighted by (target_leverage / len(assets)).

Notes

Additional keyword arguments will be forwarded to the TargetWeights constructor.

class quantopian.optimize.MaximizeAlpha(alphas)

Objective that maximizes weights.dot(alphas) for an alpha vector.

Parameters:alphas (pd.Series or dict) -- Map from assets to alpha coefficients for those assets.

Notes

Ideally, alphas should contain coefficients such that alphas[asset] is proportional to the expected return of asset for the time horizon over which the target portfolio will be held.

In the special case that alphas is an estimate of expected returns for each asset, this objective simply maximizes the expected return of the total portfolio.

This objective should almost always be used with a MaxGrossExposure constraint, and should usually be used with a PositionConcentration constraint.

Without a constraint on gross exposure, this objective will raise an error attempting to allocate an unbounded amount of capital to every asset with a nonzero alpha.

Without a constraint on individual position size, this objective will allocate all of its capital in the single asset with the largest expected return.

Constraints

class quantopian.optimize.Constraint

Base class for constraints.

class quantopian.optimize.MaxGrossExposure(max)

Constraint on the maximum gross exposure for the portfolio.

Requires that the sum of the absolute values of the portfolio weights be less than max.

Parameters:max (float) -- The maximum gross exposure of the portfolio.

Examples

MaxGrossExposure(1.5) constrains the total value of the portfolios longs and shorts to be no more than 1.5x the current portfolio value.

class quantopian.optimize.NetExposure(min, max)

Constraint on the net exposure of the portfolio.

Requires that the sum of the weights (positive or negative) of all assets in the portfolio fall between min and max.

Parameters:
  • min (float) -- The minimum net exposure of the portfolio.
  • max (float) -- The maximum net exposure of the portfolio.

Examples

NetExposure(-0.1, 0.1) constrains the difference in value between the portfolio's longs and shorts to be between -10% and 10% of the current portfolio value.

class quantopian.optimize.DollarNeutral(tolerance=0.0001)

Constraint requiring that long and short exposures must be equal-sized.

Requires that the sum of the weights (positive or negative) of all assets in the portfolio fall between +-(tolerance).

Parameters:tolerance (float, optional) -- Allowed magnitude of net market exposure. Default is 0.0001.
class quantopian.optimize.NetGroupExposure(labels, min_weights, max_weights, etf_lookthru=None)

Constraint requiring bounded net exposure to groups of assets.

Groups are defined by map from (asset -> label). Each unique label generates a constraint specifying that the sum of the weights of assets mapped to that label should fall between a lower and upper bounds.

Min/Max group exposures are specified as maps from (label -> float).

Examples of common group labels are sector, industry, and country.

Parameters:
  • labels (pd.Series[Asset -> object] or dict[Asset -> object]) -- Map from asset -> group label.
  • min_weights (pd.Series[object -> float] or dict[object -> float]) -- Map from group label to minimum net exposure to assets in that group.
  • max_weights (pd.Series[object -> float] or dict[object -> float]) -- Map from group label to maximum net exposure to assets in that group.
  • etf_lookthru (pd.DataFrame, optional) --

    Indexed by constituent assets x ETFs, expresses the weight of each constituent in each ETF.

    A DataFrame containing ETF constituents data. Each column of the frame should contain weights (from 0.0 to 1.0) representing the holdings for an ETF. Each row should contain weights for a single stock in each ETF. Columns should sum approximately to 1.0. If supplied, ETF holdings in the current and target portfolio will be decomposed into their constituents before constraints are applied.

Examples

Suppose we're interested in four stocks: AAPL, MSFT, TSLA, and GM.

AAPL and MSFT are in the technology sector. TSLA and GM are in the consumer cyclical sector. We want no more than 50% of our portfolio to be in the technology sector, and we want no more than 25% of our portfolio to be in the consumer cyclical sector.

We can construct a constraint expressing the above preferences as follows:

# Map from each asset to its sector.
labels = {AAPL: 'TECH', MSFT: 'TECH', TSLA: 'CC', GM: 'CC'}

# Maps from each sector to its min/max exposure.
min_exposures = {'TECH': -0.5, 'CC': -0.25}
max_exposures = {'TECH': 0.5, 'CC': 0.5}

constraint = NetGroupExposure(labels, min_exposures, max_exposures)

Notes

For a group that should not have a lower exposure bound, set:

min_weights[group_label] = opt.NotConstrained

For a group that should not have an upper exposure bound, set:

max_weights[group_label] = opt.NotConstrained
classmethod with_equal_bounds(cls, labels, min, max, etf_lookthru=None)

Special case constructor that applies static lower and upper bounds to all groups.

NetGroupExposure.with_equal_bounds(labels, min, max)

is equivalent to:

NetGroupExposure(
    labels=labels,
    min_weights=pd.Series(index=labels.unique(), data=min),
    max_weights=pd.Series(index=labels.unique(), data=max),
)
Parameters:
  • labels (pd.Series[Asset -> object] or dict[Asset -> object]) -- Map from asset -> group label.
  • min (float) -- Lower bound for exposure to any group.
  • max (float) -- Upper bound for exposure to any group.
class quantopian.optimize.PositionConcentration(min_weights, max_weights, default_min_weight=0.0, default_max_weight=0.0, etf_lookthru=None)

Constraint enforcing minimum/maximum position weights.

Parameters:
  • min_weights (pd.Series or dict) -- Map from asset to minimum position weight for that asset.
  • max_weights (pd.Series or dict) -- Map from asset to maximum position weight for that asset.
  • default_min_weight (float, optional) -- Value to use as a lower bound for assets not found in min_weights. Default is 0.0.
  • default_max_weight (float, optional) -- Value to use as a lower bound for assets not found in max_weights. Default is 0.0.
  • etf_lookthru (pd.DataFrame, optional) --

    Indexed by constituent assets x ETFs, expresses the weight of each constituent in each ETF.

    A DataFrame containing ETF constituents data. Each column of the frame should contain weights (from 0.0 to 1.0) representing the holdings for an ETF. Each row should contain weights for a single stock in each ETF. Columns should sum approximately to 1.0. If supplied, ETF holdings in the current and target portfolio will be decomposed into their constituents before constraints are applied.

Notes

Negative weight values are interpreted as bounds on the magnitude of short positions. A minimum weight of 0.0 constrains an asset to be long-only. A maximum weight of 0.0 constrains an asset to be short-only.

A common special case is to create a PositionConcentration constraint that applies a shared lower/upper bound to all assets. An alternate constructor, PositionConcentration.with_equal_bounds(), provides a simpler API supporting this use-case.

classmethod with_equal_bounds(min, max, etf_lookthru=None)

Special case constructor that applies static lower and upper bounds to all assets.

PositionConcentration.with_equal_bounds(min, max)

is equivalent to:

PositionConcentration(pd.Series(), pd.Series(), min, max)
Parameters:
  • min (float) -- Minimum position weight for all assets.
  • max (float) -- Maximum position weight for all assets.
class quantopian.optimize.FactorExposure(loadings, min_exposures, max_exposures)

Constraint requiring bounded net exposure to a set of risk factors.

Factor loadings are specified as a DataFrame of floats whose columns are factor labels and whose index contains Assets. Minimum and maximum factor exposures are specified as maps from factor label to min/max net exposure.

For each column in the loadings frame, we constrain:

(new_weights * loadings[column]).sum() >= min_exposure[column]
(new_weights * loadings[column]).sum() <= max_exposure[column]
Parameters:
  • loadings (pd.DataFrame) -- An (assets x labels) frame of weights for each (asset, factor) pair.
  • min_exposures (dict or pd.Series) -- Minimum net exposure values for each factor.
  • max_exposures (dict or pd.Series) -- Maximum net exposure values for each factor.
class quantopian.optimize.Pair(long, short, hedge_ratio=1.0, tolerance=0.0)

A constraint representing a pair of inverse-weighted stocks.

Parameters:
  • long (Asset) -- The asset to long.
  • short (Asset) -- The asset to short.
  • hedge_ratio (float, optional) -- The ratio between the respective absolute values of the long and short weights. Required to be greater than 0. Default is 1.0, signifying equal weighting.
  • tolerance (float, optional) -- The amount by which the hedge ratio of the calculated weights is allowed to differ from the given hedge ratio, in either direction. Required to be greater than or equal to 0. Default is 0.0.
class quantopian.optimize.Basket(assets, min_net_exposure, max_net_exposure)

Constraint requiring bounded net exposure to a basket of stocks.

Parameters:
  • assets (iterable[Asset]) -- Assets to be constrained.
  • min_net_exposure (float) -- Minimum allowed net exposure to the basket.
  • max_net_exposure (float) -- Maximum allowed net exposure to the basket.
class quantopian.optimize.Frozen(asset_or_assets, max_error_display=10)

Constraint for assets whose positions cannot change.

Parameters:asset_or_assets (Asset or sequence[Asset]) -- Asset(s) whose weight(s) cannot change.
class quantopian.optimize.ReduceOnly(asset_or_assets, max_error_display=10)

Constraint for assets whose weights can only move toward zero and cannot cross zero.

Parameters:asset (Asset) -- The asset whose position weight cannot increase in magnitude.
class quantopian.optimize.LongOnly(asset_or_assets, max_error_display=10)

Constraint for assets that cannot be held in short positions.

Parameters:asset_or_assets (Asset or iterable[Asset]) -- The asset(s) that must be long or zero.
class quantopian.optimize.ShortOnly(asset_or_assets, max_error_display=10)

Constraint for assets that cannot be held in long positions.

Parameters:asset_or_assets (Asset or iterable[Asset]) -- The asset(s) that must be short or zero.
class quantopian.optimize.FixedWeight(asset, weight)

A constraint representing an asset whose position weight is fixed as a specified value.

Parameters:
  • asset (Asset) -- The asset whose weight is fixed.
  • weight (float) -- The weight at which asset should be fixed.
class quantopian.optimize.CannotHold(asset_or_assets, max_error_display=10)

Constraint for assets whose position sizes must be 0.

Parameters:asset_or_assets (Asset or iterable[Asset]) -- The asset(s) that cannot be held.

Results and Errors

class quantopian.optimize.OptimizationResult

The result of an optimization.

raise_for_status()

Raise an error if the optimization did not succeed.

print_diagnostics()

Print diagnostic information gathered during the optimization.

old_weights

Portfolio weights before the optimization.

Type:pandas.Series
new_weights

New optimal weights, or None if the optimization failed.

Type:pandas.Series or None
diagnostics

Object containing diagnostic information about violated (or potentially violated) constraints.

Type:quantopian.optimize.Diagnostics
status

String indicating the status of the optimization.

Type:str
success

True if the optimization successfully produced a result.

Type:class:bool
class quantopian.optimize.Diagnostics

Diagnostic information about an optimization.

Notes

This object is exposed as an attribute of OptimizationResult. There is no supported way for users to construct instances of this class.

This class modifies the new_weights argument in place at construction time. All external references to new_weights should be considered invalid once new_weights has been passed to this class.

class quantopian.optimize.InfeasibleConstraints

Raised when an optimization fails because there are no valid portfolios.

This most commonly happens when the weight in some asset is simultaneously constrained to be above and below some threshold.

class quantopian.optimize.UnboundedObjective

Raised when an optimization fails because at least one weight in the 'optimal' portfolio is 'infinity'.

More formally, raised when an optimization fails because the value of an objective function improves as a value being optimized grows toward infinity, and no constraint puts a bound on the magnitude of that value.

class quantopian.optimize.OptimizationFailed

Generic exception raised when an optimization fails a reason with no special metadata.

Experimental Features

The following experimental features have been recently added to the Optimize API.

They are currently importable from quantopian.optimize.experimental. We expect to move them to quantopian.optimize once they've stabilized.

class quantopian.optimize.experimental.RiskModelExposure(risk_model_loadings, version=None, min_basic_materials=None, max_basic_materials=None, min_consumer_cyclical=None, max_consumer_cyclical=None, min_financial_services=None, max_financial_services=None, min_real_estate=None, max_real_estate=None, min_consumer_defensive=None, max_consumer_defensive=None, min_health_care=None, max_health_care=None, min_utilities=None, max_utilities=None, min_communication_services=None, max_communication_services=None, min_energy=None, max_energy=None, min_industrials=None, max_industrials=None, min_technology=None, max_technology=None, min_momentum=None, max_momentum=None, min_size=None, max_size=None, min_value=None, max_value=None, min_short_term_reversal=None, max_short_term_reversal=None, min_volatility=None, max_volatility=None)

Constraint requiring bounded net exposure to the set of risk factors provided by the Quantopian Risk Model.

Risk model loadings are specified as a DataFrame of floats whose columns are factor labels and whose index contains Assets. These are accessible via the Pipeline API using quantopian.pipeline.experimental.risk_loading_pipeline().

For each column in the risk_model_loadings frame, we constrain:

(new_weights * risk_model_loadings[column]).sum() >= min_exposure[column]
(new_weights * risk_model_loadings[column]).sum() <= max_exposure[column]

The constraint provides reasonable default bounds for each factor, which can be used with:

RiskModelExposure(risk_model_loadings, version=Newest)

To override the default bounds, each factor has optional arguments to specify a custom minimum and a custom maximum bound:

RiskModelExposure(
    risk_model_loadings,
    min_technology=-0.4,
    max_technology=0.4,
    version=Newest,
)

The default values provided by RiskModelExposure are versioned. In the event that the defaults change in the future, you can control how RiskModelExposure's behavior will change using the version parameter.

Passing version=opt.Newest causes RiskModelExposure to use the most recent defaults:

RiskModelExposure(risk_model_loadings, version=opt.Newest)

Using version=opt.Newest means that your algorithm's behavior may change in the future if the RiskModelExposure defaults change in a future release.

Passing an integer for version causes RiskModelExposure to use that particular version of the defaults:

RiskModelExposure(risk_model_loadings, version=0)

Using a fixed default version means that your algorithm's behavior will not change if the RiskModelExposure defaults change in a future release. The only fixed version number currently available is version 0. Version 0 applies bounds of (-0.18, 0.18) for each sector factor, and (-0.36, 0.36) for each style factor.

If no value is passed for version, RiskModelExposure will log a warning and use opt.Newest.

Parameters:
  • risk_model_loadings (pd.DataFrame) -- An (assets x labels) frame of weights for each (asset, factor) pair, as provided by quantopian.pipeline.experimental.risk_loading_pipeline().
  • version (int, optional) -- Version of default bounds to use. Pass opt.Newest to use the newest version. Default is Newest.
  • min_basic_materials (float, optional) -- Minimum net exposure value for the basic_materials sector risk factor.
  • max_basic_materials (float, optional) -- Maximum net exposure value for the basic_materials sector risk factor.
  • min_consumer_cyclical (float, optional) -- Minimum net exposure value for the consumer_cyclical sector risk factor.
  • max_consumer_cyclical (float, optional) -- Maximum net exposure value for the consumer_cyclical sector risk factor.
  • min_financial_services (float, optional) -- Minimum net exposure value for the financial_services sector risk factor.
  • max_financial_services (float, optional) -- Maximum net exposure value for the financial_services sector risk factor.
  • min_real_estate (float, optional) -- Minimum net exposure value for the real_estate sector risk factor.
  • max_real_estate (float, optional) -- Maximum net exposure value for the real_estate sector risk factor.
  • min_consumer_defensive (float, optional) -- Minimum net exposure value for the consumer_defensive sector risk factor.
  • max_consumer_defensive (float, optional) -- Maximum net exposure value for the consumer_defensive sector risk factor.
  • min_health_care (float, optional) -- Minimum net exposure value for the health_care sector risk factor.
  • max_health_care (float, optional) -- Maximum net exposure value for the health_care sector risk factor.
  • min_utilities (float, optional) -- Minimum net exposure value for the utilities sector risk factor.
  • max_utilities (float, optional) -- Maximum net exposure value for the utilities sector risk factor.
  • min_communication_services (float, optional) -- Minimum net exposure value for the communication_services sector risk factor.
  • max_communication_services (float, optional) -- Maximum net exposure value for the communication_services sector risk factor.
  • min_energy (float, optional) -- Minimum net exposure value for the energy sector risk factor.
  • max_energy (float, optional) -- Maximum net exposure value for the energy sector risk factor.
  • min_industrials (float, optional) -- Minimum net exposure value for the industrials sector risk factor.
  • max_industrials (float, optional) -- Maximum net exposure value for the industrials sector risk factor.
  • min_technology (float, optional) -- Minimum net exposure value for the technology sector risk factor.
  • max_technology (float, optional) -- Maximum net exposure value for the technology sector risk factor.
  • min_momentum (float, optional) -- Minimum net exposure value for the momentum style risk factor.
  • max_momentum (float, optional) -- Maximum net exposure value for the momentum style risk factor.
  • min_size (float, optional) -- Minimum net exposure value for the size style risk factor.
  • max_size (float, optional) -- Maximum net exposure value for the size style risk factor.
  • min_value (float, optional) -- Minimum net exposure value for the value style risk factor.
  • max_value (float, optional) -- Maximum net exposure value for the value style risk factor.
  • min_short_term_reversal (float, optional) -- Minimum net exposure value for the short_term_reversal style risk factor.
  • max_short_term_reversal (float, optional) -- Maximum net exposure value for the short_term_reversal style risk factor.
  • min_volatility (float, optional) -- Minimum net exposure value for the volatility style risk factor.
  • max_volatility (float, optional) -- Maximum net exposure value for the volatility style risk factor.