Java SDK Comparison
6.5 Java SDK Comparison
The Python SDK was built as a successor to the Simudyne Java SDK, maintaining compatibility with its core abstractions while extending the platform with AI agent support, a rigorous analytical layer, and modern deployment tooling. This section provides a structured comparison for teams evaluating migration or dual-SDK strategies.
Feature Matrix
| Dimension | Python SDK v0.7.0 | Simudyne Java SDK | Assessment |
|---|---|---|---|
| Core primitives | Agent, Message, Link, Action, Sequence, Split, GlobalState, Accumulator, Environment | Equivalent API surface | Parity |
| Agent types | 5 (Agent, LLMAgent, HybridAgent, RLAgent, ExternalAgentProxy) + async + cache | 1 (Agent only) | Python significantly ahead |
| Execution | 8 backends (Local, Threaded, ProcessPool, MCP, Emulator, Async, Pregel, Dask) | 2 (Local, Spark) | Python more versatile |
| Calibration | ABC-SMC, 5 prior types, compare_models, posterior predictive | None | Python only |
| Validation | Generic Feature protocol, 3 domain libraries, ablation, variance decomposition | None | Python only |
| Statistical testing | 4 tests, 4 distances, 4 corrections, bootstrap | None | Python only |
| Metrics | 27 standard metrics (21 core + 6 generic aliases) | Basic accumulators | Python significantly ahead |
| Raw throughput | ~1M agent-steps/sec (CPython) | ~10M agent-steps/sec (JVM) | Java 10x faster |
| Agent ceiling | ~100K agents practical limit | ~1M+ agents | Java scales further |
| Output | CSV, Parquet, PostgreSQL, ClickHouse, S3, DuckDB, WebSocket | CSV, Parquet, JDBC, WebSocket | Python more formats |
| Deployment | Docker, Helm (8 templates), REST API, OTel | Docker, REST API, Simudyne Studio | Java has Studio IDE |
| Hooks / Guardrails | 11 events, 4 guardrails + custom predicates | None | Python only |
| Observability | OpenTelemetry (5 spans, 7 metrics) | JMX metrics | Python more modern |
| Developer experience | pip install -e ., JSON config | Maven/Gradle, XML, JFrog credentials | Python simpler |
| Production track record | Pre-production (v0.7.0) | 15+ enterprise deployments | Java more battle-tested |
Lines of Code Comparison
Equivalent SIR epidemic model implementation:
| Aspect | Python SDK | Java SDK | Ratio |
|---|---|---|---|
| Model implementation | 45 lines | 120 lines | 2.7x |
| Configuration | 15 lines (JSON) | 40 lines (XML) | 2.7x |
| Build / packaging | 0 (pip) | 80 lines (pom.xml) | -- |
| Total | 60 lines | 240 lines | 4.0x |
Migration Guide
Key differences for teams moving from the Java SDK:
- Agent state:
__state_schema__class variable replaces typed Java fields. State fields are still typed (int, float, str, bool) but declared in a dictionary. - Messages:
agent.send(DoubleMessage, target, body=x)replacesagent.send(Messages.create(Double.class, x), target). The**payloadkeyword argument pattern replaces setter chains. - Actions:
Action.create(BankType, Bank.method)replacesAction.create("name", BankType.class, agent -> { ... }). Python uses function references instead of lambdas. - Lifecycle: Identical (
init->setup->step->done). Thesuper().setup(config)call is mandatory in both SDKs. - Seeding: Both implement the same SHA-256 hierarchy (Patent 2). Cross-SDK determinism is guaranteed for identical seeds.
- Configuration:
settings.json+config.jsonreplaces Java properties files. The three-file separation (settings/config/model) is identical in spirit. - LLM agents: Native in Python (
LLMAgent,HybridAgent), not available in Java. Models using LLM agents cannot be ported to Java. - Performance: For models exceeding 100K agents where throughput is the binding constraint, Java remains the better choice. For models under 100K agents with complex analytical requirements (calibration, validation, ablation), Python is strictly superior.
Strategic Recommendation
The two SDKs are complementary rather than competitive. The recommended workflow is: discover and validate in Python, promote to Java for maximum-scale production. Python's analytical layer (features, calibration, ablation, variance decomposition) makes it the right tool for model development, where the primary bottleneck is scientific rigour, not raw throughput. Java's JVM performance makes it the right tool for production deployment at scale, where the model is already validated and the primary requirement is throughput.
For new projects that do not require >100K agents or existing JVM infrastructure, the Python SDK is the recommended starting point. Its 4x code reduction, zero-build setup, native LLM support, and integrated analytical tooling make it the faster path to production-quality models.