model(id: String!) {
    optimization (
      positionSet: PositionSetInput!,
      base: [PositionSetInput],
      on: [Date],
      securities: OptimizationSecuritiesInput,
      objective: [OptimizationObjective]!,
      constraints: OptimizationConstraints!,
options: OptimizationOptionsInput,
      forecast: ForecastInput
    ) : ModelOptimization


The utility function that will be used to maximize / minimize for certain exposures. For a simple objective function, you can pass in an object with the name of the optimization you'd like to perform:

  • minimizeFactorRisk: Minimize factor risk across the position set.
{ "objective": { "minimizeFactorRisk": true } }
  • minimizeTotalRisk: Minimize total risk across the position set
{ "objective": { "minimizeTotalRisk": true } }
  • targetExposures: Optimize the position set to reach factor exposures to their target values.
  "objective": {
    "targetExposures": [{
      "id": "Volatility",
      "target": 1.4
      "id": "Size",
      "target": 1.2
  • targetTotalRisk / targetFactorRisk: Maximize expected return while staying below the specified risk level. A forecast should be provided in order to achieve this target.
{ "objective": { "targetTotalRisk": 0.35 } }
{ "objective": { "targetFactorRisk": 0.25 } }

Custom-Weighted Objective

Using the query.model.optimization(objective.custom) input, you can include a custom objective using one or several objective terms, allowing for the setting of the relative importance between the different objective terms. The current objective terms supported include: maximize forecast returns, minimize market impact, and minimize factor risk / stock specific risk.

Objective Options

"objective": {
"custom": {
"minimizeRisk": {
"factorRisk": {
"weight": 3
"specificRisk": {
"weight": 1
"minimizeMarketImpact": {
"weight": 10
"maximizeForecastReturn": {
"weight": 5

All terms in this custom objective are weighted relative to one another, where weights are defined to be greater than or equal to 0.

PositionSet & Base
A position set is a representation of a portfolio and uses the below notation to represent the positions in your portfolio. 

For example, this position set lists a group of securities on a specific date with an economic weight.

  "positionSet": {
    "dates": [{
      "date": "2000-01-02"
      "equities": [
          "economicExposure": 100,
          "id": {
            "mic": "XNAS",
            "ticker": "GOOGL"
          "economicExposure": 100,
          "id": {
            "mic": "XNAS",
            "ticker": "GOOG"

Learn more about Using Position Sets

A base uses the same structure as a position set and represents a benchmark or another portfolio that you would like to run an active optimization against.

A Note on Optimization Dates

The base must use the same date as the position set, and the optimizer will take the first date from the position set to perform the optimization.

The On input is used in conjunction with a positionSet whenever the PositionSetInput directly references a portfolio by using its ID. The on date is used to identify which date the optimization should take place on.

  positionSet: {
    type: PORTFOLIO,
    id: "portfolio_id"
  base: {
    type: BENCHMARK,
    id: "benchmark_id"
  on: "2000-01-02"

Securities (input*)

The securities input can take in a security universe -- a list of securities not currently in your position set -- and find the optimal positioning for those securities for the specified long or short side of the optimization.

Securities can be configured in one of many ways: 

  • Providing a watchlist
  • Adding equity names on-the-fly
  • Performing a security search across the model universe against specific filters
  • A combination of any of the above, using a watchlist, on-the-fly names and/or security search, shown below:
  securities: {
    short: {
      id: "watchlist_id",
      type: "WATCHLIST",
      equities: [{
        id: {
          ticker: "MSFT",
          mic: "XNAS"
"securitySearch": {
"filter": {
"averageDailyVolume": {
"gt": 1000000
"universe": {
"type": "ETF",
"in": "SPY.ARCX"

Here we see the structure referencing an existing watchlist. This will pull in all the securities associated with this watchlist as part of the security universe. Learn more about watchlists

In addition, this structure augments the watchlist with on-the-fly equities, passing in an array of IDs to either the long or short side of the book.

Note that these securities lists do not contain a date nor economicExposure as they are external names that may be added to the optimized position set.

Note on Short Market Value, Long Market Value
When adding securities, the optimizer needs to know how much market value to target, longMarketValue or shortMarketValue. The market value is defined as the total economic exposure of that side of the book. This lets the optimizer know how much it can buy into as it adds the external names to the overall book.

*Please note:

This is optimization( securities: {...} ) input, not to be confused with the optimization(constraints.securities) constraint, which is used to provide per-security min / max limitations.


Constraints are used to filter out possible optimizations.

  "exposure": [{
    "id": "Volatility",
    "max": 1.5,
    "min": 0.5
  "composition": [
      "id": "451030",
      "type": "INDUSTRY",
      "minEconomicExposure": 1000000,
      "maxEconomicExposure": 2000000
  "maxConcentration": 0.3,
  "minConcentration": 0.1,
  "maxTurnover": 1,
  "maxLiquidationDays": 1,
  "minTrade": 0.1,
  "maxTrade": {
      "percentEquity": 2.0,
      "percentOriginalEconomicExposure": 25.0,
      "percentADV": 50.0
"risk": {
"total": { "max": 50 }
"factor": { "max": 35 }
  "longMarketValue": 700000,
  "shortMarketValue": 300000,
  "maxPositions": 50,
"netExposure": 9000000,
  "securities": [{
    "id": { "ticker": "MSFT", "mic": "XNAS" },
    "maxEconomicExposure": 1500000,
    "minEconomicExposure": 1000000
  "securityMinTrade": [{
    "id": { "sedol": 1234567 },
    "minTrade": .1
"fixPositionSetSecurities": false,
"beta": {
"min": 0.1,
"max": 0.2
"min": 0.1,
"max": 0.2

Here is the list of possible constraints to use:

  • exposure
    A list of minimum and maximum values for factor exposures. This sets an acceptable range, whereas objective.targetExposures aims to get as close as possible to the target value.
  • composition
    A list of minimum and maximum economic exposure values for securities to be constrained on a composition type, such as sector, industry, industry group, country, or currency.
  • maxConcentration
    Maximum proportion of GMV that any single security may hold.
  • minConcentration
    Minimum proportion of GMV that any single security may hold.
  • maxTurnover
    The percent of the positionSet that can be traded during the optimization.
  • maxLiquidationDays
    Constrains the trade size for a single security to not exceed this multiple of the average daily volume. A.K.A. max trade size (% ADV).
  • minTrade
    Minimum single security trade size as a proportion of equity.
  • maxTrade: { ... }
    Limit the possible trade size on any single security
  • maxTrade.percentEquity
    If the security is at 5% and you want to limit to 5% +/- 2%, then use percentEquity: 2.0
  • maxTrade.percentOriginalEconomicExposure
    If the security is at 5% and you want to limit to 50% of its original size (e.g.  5% +/- 2.5%) then use percentOriginalEconomicExposure = 50.0
  • maxTrade.percentADV
    Maximum per security trade size as a percentage of average daily volume
  • risk: {...}
    Constrains the optimization space based on the maximum percent total risk or factor risk provided with and/or risk.factor.max
  • longMarketValue
    Total absolute value of economic exposures across long positions. Min, max LMV values can be defined using minLongMarketValue and/or maxLongMarketValue
  • shortMarketValue
    Total absolute value of economic exposures across short positions. Min, max SMV values can be defined using minShortMarketValue and/or maxShortMarketValue
  • maxPositions
    The maximum number of positions in the optimized portfolio.
  • netExposure
    Total sum of long positions minus sum of short positions, divided by equity. Min, max values can be defined using minNetExposure and/or maxNetExposure
  • securities (constraint*)
    Minimum and Maximum allowed position sizes for individual securities. This is passed in as an array of securities, and the optimizer will not exceed the min / max economic exposure targets in dollar units.
    Note: Min / max can be equal to each other, which will fix the price target for the associated security.
    *This is optimization(constraints.securities), not to be confused with the optimization(securities) input, which passes in a security universe for consideration.
  • securityMinTrade
    A list of minimum allowed trade sizes for individual securities.
  • fixPositionSetSecurities
    Set to true so that securities in the portfolio are not traded, allowing securities from a watchlist or security search to be traded.
  • beta
    Set minimum and maximum beta values for predicted and historical beta

Forecast & Market Impact

A forecast is a prediction or estimate of future events that can be used to refine the optimization, with an associated time horizon (in trading days).

  "horizon": 20,
  "equities": [{
    "id": { "ticker": "MSFT", "mic": "XNAS" },
    "expectedPercentReturn": 0.12
  }, {
    "id": { "sedol": 1234567 },
    "expectedPercentReturn": 0.275,
    "marketImpact": [{
      "tradeSize": 120000,
      "percentImpact": 0.01

Market impact is a list of { tradeSize, percentImpact } pairs per security:

  • tradeSize is in units of currency. If tradeSize is not present, the trade size in units of percent average daily volume can be used be sending in tradePercentAverageDailyVolume.
  • percentImpact which represents the impact on price given this trade size, in units of percent.

Did this answer your question?