Developer guide

This section is a developer-facing guide. The canonical source of truth for internal rules and conventions is devguide/. If there is any conflict, devguide/ takes precedence.

Introduction

• Introduction
• Intro
• Fork MolSysMT
  • Clone your fork
  • Work with a conda environment
  • Install it
• Reporting bugs and proposals
  • If you are using MolSysMT
  • What happens to your report
  • How it closes
  • If you are working inside the repository
• Development Environment Setup Guide
  • 🚀 Basic Usage
    • 1. Setup without activation
    • 2. Setup and persist activation
  • 🐍 Choosing Python Version
  • 📂 Flexible Execution Paths
  • ⚙️ Options
  • 📊 Diagnostics
  • ✅ Summary
• Contributing: Development Environment with Devcontainers
  • 📦 How it works
  • 🚀 Usage
  • ✅ Advantages over a simple startup script
  • 🔒 Optional: conda-lock
  • 🧭 Summary
• Dependency Management Architecture
  • 1. Core Principles
  • 2. Configuration & Mapping
    • Dependency Definitions (molsysmt/_depdigest.py)
    • Form Directory Mapping
  • 3. The @dep_digest Decorator
  • 4. The Lazy Form Loader (molsysmt.form)
  • 5. Validation Script
  • 6. Integration Testing
  • 7. User Introspection
  • 8. How to Add a New Dependency
  • 7. Troubleshooting
• Element Queries and Native Rebuild
  • Architecture
  • Native Rebuild APIs
  • Semantic Contract
  • Canonical Fallbacks
  • Current Consolidation Status
  • External Enrichment
• MolSysBuilder
  • Why it matters for converter tests
  • Editing policy
  • Preferred testing pattern
  • Current supported builder surface
• Declarative Serialization Forms
  • Why this exists
  • MolSysDict 0.1 fidelity boundary
  • Naming model
  • Relationship with existing JSON payloads
  • Current checkpoint
  • Second slice checkpoint
  • Third slice checkpoint

New form

• Adding a new form

Heavy trajectories

• Heavy trajectory infrastructure
  • Architecture overview
  • The Reducer ABC
    • Mandatory interface
    • metadata keys (passed to initialize)
    • chunk keys (passed to consume)
    • Optional extensions
    • Minimal example
  • ChunkedExecutor usage
    • The attributes parameter
    • Multi-reducer (read-once, analyze-many)
    • Checkpoint / resume
    • User-controlled output path
    • Parallel reduction via merge()
  • Adding heavy support to a form
    • 1. Declare _heavy_support
    • 2. Implement StructuresIterator
  • SMonitor event codes
  • Relevant source files

Performance & Benchmarking

• Performance & Benchmarking
  • Interactive Performance Dashboard
  • Benchmarking Philosophy & Telemetry
  • Running the Benchmark Suite
    • 1. Generating a Performance Run
    • 2. Auditing for Regressions

Warnings

• MolSysMT Warning Catalog (via smonitor)
  • 1) Catalog-driven design
  • 2) Example catalog entry
  • 3) Emitting a warning
  • 4) Message quality rules
  • 5) Deprecations and legacy categories
  • 6) Testing warnings
• MolSysMT Diagnostics and Logging (via smonitor)
  • 1) Overview
  • 2) Where configuration lives
  • 3) Where catalog and metadata live
  • 4) Emitting warnings and errors
  • 5) Runtime overrides (user control)
  • 6) Testing diagnostics
  • 7) Legacy note
• SMonitor integration
  • Files
  • Emission pattern
  • Guidance

Tests

• Testing
  • Unit Tests
  • Continuous Integration
  • Code Coverage

Documentation

• API documentation guidelines
  • Docstrings
  • Doctests
• Documentation for the web
  • MyST in MolSysMT documentation
  • References and Cross-links in Documentation