Volt: Open-Source Options Portfolio Logic

Volt represents option portfolios as listed contracts, signed positions, lifecycle actions, and scenario observations. That representation gives valuation, optimization, and learning systems a precise record of what a portfolio holds and how it behaves.

This article follows the representation through compilation, portfolio search, and reuse of contract-level calculations. It explains how positions, payoffs, Greeks, path statistics, and costs provide the evidence used to compare candidate portfolios and evaluate subsequent actions.

Why make this logic open source?

The code that defines a portfolio should be as inspectable as the research that uses it. A researcher should be able to check which contract was selected, which quote was used, how positions were combined, and what happened at exercise or assignment. Those details determine whether a result can be reproduced.

Making this layer public also separates common infrastructure from investment decisions. Contract definitions, portfolio compilation, scenario accounting, and graph export are reusable. A firm's data, forecasts, objectives, account rules, and decision to trade can remain private.

Volt is released under Apache-2.0. The library is useful to teams building portfolio search, backtests, risk services, or learning systems that propose multi-leg positions. It is not needed for a simple payoff chart or a broker order ticket.

What the compiler produces

Volt starts with the listed contract. An OptionContract records the identifier, underlying, currency, call or put right, strike, multiplier, exercise dates, and settlement method. A position adds a signed quantity.

If a candidate contains two long contracts and one short contract with the same identifier, canonicalization produces one long contract. If the long and short quantities offset completely, the position disappears. The remaining positions are sorted in a stable order, so the same economic input produces the same compiled portfolio.

Volt does not merge different listed contracts simply because their payoff charts happen to match. The repository includes a test with two $100 calls, VENUE-A-C100 and VENUE-B-C100. They have the same payoff at expiry, but they retain different portfolio identifiers because they are different contracts.

For calculations that only need the expiry shape, Volt can also express the compiled portfolio as:

\[\text{cash} + \text{underlying units}\times S + \sum_k w_k\max(S-K_k,0).\]

Here \(S\) is the underlying price at expiry. This form is useful for comparing payoff shapes, but the original compiled portfolio still records the exact contracts that would have to be valued or traded.

The zap example shows the reduction directly. Its 144 ordered two-action results compile into 73 portfolios after offsets and ordering duplicates are removed. A larger run produces 15,625 exact portfolios and 13,321 distinct payoff shapes. The commands and counts are in the reproducible results.

Searching without starting from a strategy name

Most options screeners begin with a catalogue: vertical, straddle, butterfly, calendar, and so on. That makes the search manageable, but it decides the number of legs and their sign pattern before the portfolio has been evaluated.

Volt begins with the contracts available at a particular observation time and a set of constraints. CandidateGrammar can request a call in a strike or expiry range, resolve the request to the contracts that actually existed, and reject actions that are not legal. The compiler then turns the selected actions into canonical portfolios.

This does not prevent familiar strategies from appearing. It simply applies their names after the search rather than using the names to define the search space. A selected portfolio may turn out to be a bear call spread. Another may not match the reference catalogue at all.

The strategy-discovery pilot searched up to three legs drawn from twelve American option contracts. It produced 1,335 canonical portfolios and evaluated them over 512 paths, or 683,520 candidate-path combinations in the exhaustive run. One selected two-call portfolio had no exact match in the deliberately small comparison catalogue. That is not proof of a new or profitable strategy; it demonstrates that the search was not limited to the catalogue.

Reusing calculations across portfolios

Portfolio search repeats a great deal of work if every candidate is valued from scratch. The same option contract can appear in thousands of different combinations.

In Volt's research workflow, American marks, exercise checks, and pathwise sensitivities are calculated once per contract. A portfolio is then evaluated as a signed aggregation of those compiled leg paths, followed by hedge and account calculations.

The empirical event study used fourteen American options. It generated 12,313 bounded combinations, of which 7,208 passed the account filters. Once the common contract calculations were available, aggregating 4,000 portfolios for the daily-hedge calculation took 0.152 seconds in the recorded benchmark. This is the practical reason for compiling the legs before placing the process inside a larger optimization loop.

Using the portfolio in a learning system

PortfolioGraphSample exports a compiled portfolio as typed nodes and edges. The graph contains the exact portfolio identifier, the payoff identifier, and the supplied market features. A model can use that structure to predict an objective, rank candidates, or produce an embedding without losing the route back to the listed contracts.

The reference graph experiment uses six contracts with quantities of -1, 0, or 1. It exports all \(3^6=729\) portfolios to JSON Lines and uses them in a supervised comparison of a relation-aware graph network, Deep Sets, and a linear baseline. The comparison evaluates the learning interface against direct portfolio calculation. In the later event study, direct compiled evaluation remained faster at the measured portfolio counts, and the learned models did not recover an exact optimum on a later date.

For AI explanation, the useful output is not just the graph. The research workflow builds an evidence packet from the evaluation: exact positions, payoff geometry, entry Greeks, path statistics, costs, leg attribution, and exercise or assignment counts. An AI system can turn those computed fields into an explanation while keeping every numerical claim tied to the evaluation. The same evidence can be checked by a person or another program.

What happens after a portfolio is selected

Options can be exercised, assigned, expired, or closed before the end of a simulation. Volt records those actions against the same compiled position.

For example, exercising one physically settled SPY call with a \(100 strike and a multiplier of 100 posts a \)10,000 cash payment, adds 100 SPY shares, and removes the option. The runtime checks the exercise schedule first. An early exercise of a European option is rejected, and assignment of a short option is recorded separately from exercise by its holder.

The simulator also separates a valuation mark from an executable price. Under CrossAtTouch, a purchase requires an ask and a sale requires a bid. A test with a \(1.90 bid and a \)2.00 last-trade mark rejects the purchase because the required ask is missing. The simulation tests include the quotes, fills, fees, and reconciliation.

What Volt includes

The risk and risk_server examples run a four-leg, cash-settled European iron condor. A generated path updates option marks, Greeks, portfolio value, and the expiration diagram. The pricer is a teaching model, so the output demonstrates the program rather than a live market or a tested trading strategy.

The live walkthrough includes the terminal recording and browser version shown above. The program guide lists the runnable examples.

Three papers develop the representation and proposed search and control work: Financial Semantics for Option Portfolio Graphs, Searching the Option Strategy Space, and Sequential Control of Option Portfolios. The repository contains their source copies and the code used in the examples.

The empirical study Option Portfolio Selection Around Two Event Shocks: SPY Tariffs, USO Conflict Risk, and Volatility Forecasts applies the compiler and path evaluator to option chains observed before the April 2025 tariff escalation and the February 2026 US–Iran conflict. At the stated event probabilities, the SPY study selects three adjacent long puts and the USO study selects an 80/83 call spread. A separate delta-hedged analysis changes from short to long gamma as forecast realized volatility rises through the entry implied-volatility range.

Where Volt fits in StrategyNet

Volt is intended to be used with the other applications in the StrategyNet stack. Hypercube maintains changing analytical fields and makes the current state available to its readers. Volt can use that state to construct and evaluate a legal option portfolio.

Jörmungandr provides the distributed reinforcement-learning layer. In a combined application, a Volt-based actor defines the option environment, available actions, portfolio transitions, and rewards. Jörmungandr receives the resulting experience and learns a policy without having to reproduce option contracts, exercise rules, or account logic inside the learner.

The division is practical. Hypercube maintains the analytical state, Volt turns that state into option portfolios and evaluated outcomes, and Jörmungandr learns from repeated decisions. Each component can also be used on its own.

Volt does not supply live market data, decide which pricing model is correct, set account policy, or send orders. It provides the portfolio compiler, lifecycle rules, scenario interface, and graph representation that those systems can use. A production system must still provide market observations, valuation models, objectives, limits, and execution authority.

The current release is 0.1.4. Its Cargo package is volt-options; Rust code imports the library as volt.

Browse the Volt source.