Code Generation API Reference

The mechanics_dsl.codegen package provides code generation backends for compiling MechanicsDSL simulations to various target platforms.

Base Classes

CodeGenerator

class mechanics_dsl.codegen.CodeGenerator

Abstract base class for code generation backends.

Attributes:

  • system_name: Physics system name

  • coordinates: Generalized coordinates

  • parameters: Physical parameters

  • initial_conditions: Initial state

  • equations: Symbolic equations

Abstract Properties:

  • target_name: Target platform name (e.g., ‘cpp’, ‘python’)

  • file_extension: Output file extension (e.g., ‘.cpp’, ‘.py’)

Abstract Methods:

abstract generate(output_file: str) → str

Generate code and write to file.

abstract generate_equations() → str

Generate equations of motion code.

Common Methods:

generate_parameters() → str

Generate parameter declarations.

generate_initial_conditions() → str

Generate initial condition setup.

validate() → Tuple[bool, List[str]]

Validate generator has all required data.

C++ Backend

CppGenerator

class mechanics_dsl.codegen.CppGenerator

Generates optimized C++ simulation code.

Example:

from mechanics_dsl.codegen import CppGenerator

generator = CppGenerator(
    system_name="pendulum",
    coordinates=["theta"],
    parameters={"m": 1.0, "l": 1.0, "g": 9.81},
    initial_conditions={"theta": 0.5, "theta_dot": 0.0},
    equations={"theta_ddot": symbolic_expr}
)

generator.generate("simulation.cpp")

Constructor:

__init__(system_name, coordinates, parameters, initial_conditions, equations, fluid_particles=None, boundary_particles=None)
Parameters:

  • fluid_particles – List of SPH particles (for fluid simulations)

  • boundary_particles – List of boundary particles

Methods:

generate(output_file: str = 'simulation.cpp') → str

Generate C++ file with RK4 integration.

Generated Code Features:

  • RK4 integration algorithm

  • CSV output for results

  • SPH spatial hashing (for fluids)

  • OpenMP parallelization (optional)

Python Backend

PythonGenerator

class mechanics_dsl.codegen.python.PythonGenerator

Generates standalone Python simulation scripts using NumPy/SciPy.

Example:

from mechanics_dsl.codegen.python import PythonGenerator

generator = PythonGenerator(
    system_name="double_pendulum",
    coordinates=["theta1", "theta2"],
    parameters={"m1": 1.0, "m2": 1.0, "l1": 1.0, "l2": 1.0, "g": 9.81},
    initial_conditions={...},
    equations={...}
)

generator.generate("double_pendulum_sim.py")

Generated Script Features:

  • NumPy array operations

  • SciPy solve_ivp integration

  • Matplotlib visualization

  • Runnable as standalone script

I/O API Reference

The mechanics_dsl.io package provides file input/output, serialization, and data export utilities.

SystemSerializer

class mechanics_dsl.io.SystemSerializer

Serializer for physics system configurations.

Example:

from mechanics_dsl.io import SystemSerializer

# Save to JSON
SystemSerializer.save_json(data, "system.json")

# Load from JSON
data = SystemSerializer.load_json("system.json")

# Pickle for full Python object preservation
SystemSerializer.save_pickle(data, "system.pkl")
data = SystemSerializer.load_pickle("system.pkl")

Class Methods:

static save_json(data: dict, filename: str) → bool

Save data to JSON file.

static load_json(filename: str) → dict | None

Load data from JSON file.

static save_pickle(data: dict, filename: str) → bool

Save data to pickle file.

static load_pickle(filename: str) → dict | None

Load data from pickle file.

Convenience Functions

mechanics_dsl.io.serialize_solution(solution, filename, format='json')

Serialize simulation solution to file.

Parameters:

  • solution – Solution dictionary

  • filename – Output path

  • format – ‘json’ or ‘pickle’

mechanics_dsl.io.deserialize_solution(filename, format=None)

Load simulation solution from file.

Parameters:

  • filename – Input path

  • format – Auto-detected if None

CSVExporter

class mechanics_dsl.io.CSVExporter

Export simulation data to CSV format.

Example:

from mechanics_dsl.io import CSVExporter

# Export solution
CSVExporter.export_solution(solution, "results.csv")

# Export custom table
CSVExporter.export_table({
    't': time_array,
    'energy': energy_array,
    'error': error_array
}, "analysis.csv")

Class Methods:

static export_solution(solution, filename, include_time=True)

Export simulation solution to CSV.

static export_table(data: dict, filename: str)

Export dictionary of arrays as columns.

JSONExporter

class mechanics_dsl.io.JSONExporter

Export simulation data to JSON format.

Class Methods:

static export_solution(solution, filename, compact=False)

Export solution to JSON.

static export_parameters(parameters, filename)

Export parameters to JSON.