Optimize API Reference¶
The Optimize API allows Quantopian users to describe their desired orders in terms of highlevel Objectives and Constraints.
Contents
See also
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 alreadycomputed 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 equalsized. 
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 inverseweighted 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:  objective (quantopian.optimize.Objective)  The objective to be minimized/maximized by the new portfolio.
 constraints (list[quantopian.optimize.Constraint])  Constraints that must be respected by the new portfolio.
 universe (object)  This parameter is deprecated and ignored.
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 anyconstraints
. Weights should be interpreted in the same way ascurrent_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'snew_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:
Objectives¶

class
quantopian.optimize.
Objective
¶ Base class for objectives.

class
quantopian.optimize.
TargetWeights
(weights)¶ Objective that minimizes the distance from an alreadycomputed 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 producew_target
ifw_target
satisfies all optimization constraints.If
w_target
violates one or more constraints, this objective will find the feasible portfolio closest tow_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 equalweight target portfolio.
Parameters: Notes
Additional keyword arguments will be forwarded to the TargetWeights constructor.

classmethod

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 thatalphas[asset]
is proportional to the expected return ofasset
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
andmax
.Parameters: 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 equalsized.
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:

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 longonly. A maximum weight of 0.0 constrains an asset to be shortonly.
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 usecase.
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:

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:

class
quantopian.optimize.
Pair
(long, short, hedge_ratio=1.0, tolerance=0.0)¶ A constraint representing a pair of inverseweighted 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:

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:
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

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 tonew_weights
should be considered invalid oncenew_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 useopt.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 isNewest
.  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.
 risk_model_loadings (pd.DataFrame)  An (assets x labels) frame of weights for each (asset, factor) pair,
as provided by