MarS financial market simulation with generative order models

What MarS models beyond price returns

MarS addresses a specific problem in financial research: simulating how generated orders and changing market state produce an evolving market rather than replaying only a historical price series. Microsoft describes it as a financial market simulation engine powered by a generative foundation model. The released assets center on an order model, with 2M, 5M, and 10M parameter versions published in separate Hugging Face repositories.

The project is intended for researchers and engineers studying market formation, order generation, market impact, forecasting, and aggregate market behavior. The repository includes examples for analyzing 11 market characteristics, simulating future prediction, examining market impact, and opening an interactive Streamlit interface. These are research workflows. The README does not describe interfaces for placing live orders, routing transactions to a broker, managing positions, or calculating portfolio returns.

MarS is therefore more specific than a conventional backtester. Its basic unit of interest appears to be an order and the state produced when orders interact with a simulated market. That design can support questions about aggregate effects of agent behavior, but it also shifts the burden of validation toward order constraints and state-transition rules. A believable historical price path is not, by itself, evidence that the generated order process is plausible.

The available model sizes define a clear release boundary. The README lists 2M, 5M, and 10M models as released. It lists 19M, 44M, 107M, 221M, and 1.02B models as unreleased because approval from Microsoft's Corporate, External, and Legal Affairs team was still being requested. Users cannot treat the scaling-law figure in the README as a promise that larger downloadable models are currently available.

OrderModel, OrderState, and BackgroundAgent

The repository layout identifies the principal mechanism. `market_simulation/models/order_model.py` contains `OrderModel`, which the README says generates orders. `market_simulation/states/order_state.py` contains `OrderState`, which represents and updates market state. `market_simulation/agents/background_agent.py` contains `BackgroundAgent`, the component responsible for initiating order generation.

These modules imply a state-driven loop. `OrderState` supplies a representation of the simulated market, `BackgroundAgent` coordinates activity that produces orders, and `OrderModel` generates those orders. Generated orders must then affect the state before the simulation can continue. This architecture is useful for research because the representation, generator, and agent coordination have separate source files rather than being combined into one opaque entry point.

The README also states that the order model is served through Ray Serve. The client and server exchange data in a fixed-size, little-endian `int32` binary format. That format couples the serving layer to MarS's internal numerical representation. Adopters should treat the endpoint as an internal service contract unless their own integration work explicitly wraps it.

The available documentation does not disclose sampling settings, conditioning representation, order validity rules, matching mechanics, transaction costs, or state-update equations. Those details cannot be inferred safely from module names. They need review in the source files before a user claims that the simulation reproduces a target market.

Docker setup for the Linux GPU workflow

MarS explicitly does not support direct installation without Docker because of system dependencies and CUDA requirements. The README badges identify Linux, Python 3.11 or 3.12, and the `dev` extra. The recommended path uses VS Code Dev Containers, while the direct Docker path creates an image from `.devcontainer/Dockerfile`.

Begin by cloning the repository:

git clone https://github.com/microsoft/MarS.git
cd MarS

After the container is active, install the project and development dependencies:

pip install -e .[dev]

For the direct Docker route, build the documented image:

docker build -t mars-env -f .devcontainer/Dockerfile .

The documented launch command uses a host data path, all GPUs, a 20 GB shared-memory allocation, and a privileged container. Replace `<your/data/path>` with an existing host directory.

docker run -it --cap-add=SYS_ADMIN --device=/dev/fuse --security-opt=apparmor:unconfined --shm-size=20gb --gpus=all --privileged -v <your/data/path>:/data -v $(pwd):/workspaces/MarS -w /workspaces/MarS mars-env

The README advises exposing the model endpoint to remote clients only behind network access controls and authentication. The command itself contains broad container permissions, so the documentation's Docker-first recommendation should be read as an operational constraint, not merely a convenience.

Downloading the 10M model and starting Ray Serve

After installation, `download.py` retrieves the model, converters, validation samples, and stylized-facts data. The 10M model is the default:

python download.py

The README warns that this operation needs sufficient disk space and may take time. Users who want the 2M model can set the documented serving repository variable first:

export MODEL_SERVING__REPO_ID=Don-Don/mars-order-2m
python download.py

MarS then deploys the order model through Ray Serve:

bash scripts/start-order-model.sh

The order-model HTTP endpoint listens on `localhost` by default. The server and client must use the same MarS version because requests and responses use the fixed binary representation described by the README. Sufficient computing resources are also required.

Once the service is available, the documented interactive entry point starts the demo applications:

streamlit run market_simulation/examples/demo/home_app.py

This sequence is the clearest first-use path: prepare the container, install the package, download model assets, start the model server, and launch Streamlit. The README does not state what exact text or metrics should appear in the interface, so the absence of errors is the only terminal condition confirmed by the instructions.

Stylized facts, forecasting, and market impact studies

The examples indicate several intended research outputs. `market_simulation/examples/report_stylized_facts.py` evaluates 11 key market characteristics. This is useful when the central question is whether a simulation reproduces aggregate statistical patterns. A passing result therefore requires criteria chosen for the user's research rather than an undocumented MarS certification.

`market_simulation/examples/forecast.py` presents simulation as forecasting. The repository describes this as exploring future prediction, but it does not claim that the model is a trading forecast service or that its predictions are suitable for autonomous decisions. A simulated future path is conditioned by the environment, agents, and assumptions encoded in MarS. It should not be read automatically as an empirical prediction with documented production accuracy.

`market_simulation/examples/market_impact.py` addresses the effect of orders on market behavior. This is the closest documented use case to transaction-cost analysis, but the README does not say whether the example implements a canonical market impact model, estimates a learned effect, or supports specific order types. Those distinctions require inspection before results are used in execution research.

The README also discusses an order-model scaling-law curve. It states that validation loss decreases as model size and number of training tokens increase. It supports a size-versus-loss observation, not a claim about investment performance.

Operational limits, licensing, and release status

MarS has meaningful operational constraints. Direct host installation is unsupported, the documented platform is Linux, CUDA is required, and the Docker command assumes GPU access. The 20 GB shared-memory setting is also unusually large, although the README does not explain which workloads need that allocation. A user with macOS, Windows without the documented container path, or a host without suitable GPU hardware will need to solve those constraints before evaluation.

The endpoint deserves attention because MarS distributes computation between a client and a model server. Binding it only to `localhost` reduces accidental exposure, but the README explicitly requires access controls and authentication before remote exposure. It does not document a production authentication configuration, TLS setup, authorization model, or rollback procedure. The service should not be placed on an untrusted network merely because the repository calls the deployment scalable and production-ready.

The project uses the MIT license. The repository does not separately state terms for market datasets, financial inputs, validation samples, or stylized-facts assets. MIT coverage for source code should not be assumed to settle rights for every downloaded data file. Users need to inspect notices and terms attached to each asset separately.

The repository is not archived, and the last push was on 2026-09-28. Version 0.1.0 was released on 2026-09-24. This indicates recent project activity, but the low version number matters for adoption planning. MarS is an early release with limited documented API guarantees. Upgrading may require matching the Ray Serve client and server versions and rechecking binary compatibility.

MarS compared with deterministic market simulation

The real alternative is a deterministic, rules-based market simulator. Such an engine advances orders through explicit matching, queue, fill, transaction-cost, and market-state rules. Its parameters are selected and interpreted by the researcher, and identical inputs and rules should produce an identical path, subject to documented randomness controls. This differs from MarS's generative order approach, where `OrderModel` learns order generation from training data and Ray Serve exposes the resulting model as a service.

A deterministic simulator is easier to audit when the goal is to isolate the effect of a modified fee, matching rule, or order policy. MarS is more appropriate when the research question depends on modeled agent or order distributions that are difficult to specify completely as rules. The trade-off is validation complexity. A generated order process can express richer behavior, but its fidelity depends on training data, sampling behavior, model size, and state-transition assumptions.

Neither approach automatically makes simulated prices tradable. MarS's model-size table and stylized-fact examples can support research into learned order behavior, but they do not replace execution validation against the intended market. An engineer needing deterministic transaction-cost scenarios may prefer the rules-based route. A researcher studying emergent market statistics from generated orders has a clearer reason to assess MarS.

Editorial conclusion

Researchers should consider MarS for order-driven market simulation, generated agents, and research into market formation. Production trading firms and engineers seeking a lightweight backtester or execution engine should not adopt it without checking data rights, network isolation, model validity, GPU requirements, and operating costs. First verify that the Linux and CUDA environment can start the documented Ray Serve endpoint.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. microsoft/MarS on GitHub
4. README
5. Releases