experimental: add synchronous run_simulation (#390)

- No asynchronous implementation as that'll be mildly different.
- No docs.
- One example, no tests. Python unit tests for simulations aren't
  really feasible as things stand.
- Tested manually using the example.
- No handling of log or dataset returns, the current server doesn't
  send those.
- No handling of resolution.
- No handling of scenarios, which is currently not supported on the
  server.
- Interface subject to change.

See Volue/energy-sim#742.

docs/source/examples.rst

@@ -103,3 +103,8 @@ Write time series, asynchronously
 .. literalinclude:: /../../src/volue/mesh/examples/write_timeseries_points_async.py
    :language: python
 
+Run simulations
+***************
+.. literalinclude:: /../../src/volue/mesh/examples/run_simulation.py
+   :language: python
+

src/volue/mesh/_connection.py

@@ -30,7 +30,9 @@
     _to_proto_guid,
     _from_proto_guid,
     _to_proto_timeseries,
+    _to_proto_utcinterval,
 )
+from volue.mesh._mesh_id import _to_proto_object_mesh_id
 from volue.mesh.calc.forecast import ForecastFunctions
 from volue.mesh.calc.history import HistoryFunctions
 from volue.mesh.calc.statistical import StatisticalFunctions
@@ -374,6 +376,33 @@ def update_rating_curve_versions(
             )
             self.mesh_service.UpdateRatingCurveVersions(request)
 
+        def run_simulation(
+            self,
+            model: str,
+            case_group: str,
+            case: str,
+            start_time: datetime,
+            end_time: datetime,
+            resolution: Timeseries.Resolution,
+            scenario: int,
+            return_datasets: bool,
+        ) -> typing.Iterator[None]:
+            if start_time is None or end_time is None:
+                raise TypeError("start_time and end_time must both have a value")
+
+            simulation = f"Model/{model}/{case_group}.has_OptimisationCases/{case}.has_OptimisationParameters/Optimal.has_HydroSimulation/HydroSimulation"
+
+            request = core_pb2.SimulationRequest(
+                session_id=_to_proto_guid(self.session_id),
+                simulation=_to_proto_object_mesh_id(simulation),
+                interval=_to_proto_utcinterval(start_time, end_time),
+                scenario=scenario,
+                return_datasets=return_datasets,
+            )
+
+            for response in self.mesh_service.RunHydroSimulation(request):
+                yield None
+
     @staticmethod
     def _secure_grpc_channel(*args, **kwargs):
         return grpc.secure_channel(*args, **kwargs)

src/volue/mesh/examples/run_simulation.py

@@ -0,0 +1,29 @@
+from datetime import datetime
+
+from volue import mesh
+from volue.mesh.examples import _get_connection_info
+
+
+def main(address, port, root_pem_certificate):
+    print("connecting...")
+    connection = mesh.Connection(address, port, root_pem_certificate)
+
+    with connection.create_session() as session:
+        start_time = datetime(2023, 11, 1)
+        end_time = datetime(2023, 11, 2)
+
+        print("running simulation...")
+
+        try:
+            for response in session.run_simulation(
+                "Mesh", "Cases", "Demo", start_time, end_time, None, 0, False
+            ):
+                pass
+            print("done")
+        except Exception as e:
+            print(f"failed to run simulation: {e}")
+
+
+if __name__ == "__main__":
+    address, port, root_pem_certificate = _get_connection_info()
+    main(address, port, root_pem_certificate)

src/volue/mesh/proto/core/v1alpha/core.proto

@@ -245,6 +245,7 @@ service MeshService {
   rpc GetTextResource(GetTextResourceRequest) returns (GetTextResourceResponse) {}
   rpc WriteTextResource(WriteTextResourceRequest) returns (WriteTextResourceResponse) {}
 
+  rpc RunHydroSimulation(SimulationRequest) returns (stream SimulationResponse) {}
 }
 
 message AuthenticateKerberosResponse {
@@ -1255,3 +1256,14 @@ message WriteTextResourceRequest {
 }
 
 message WriteTextResourceResponse {}
+
+message SimulationRequest {
+    volue.mesh.grpc.type.Guid session_id = 1;
+    MeshId simulation = 2;
+    volue.mesh.grpc.type.UtcInterval interval = 3;
+    volue.mesh.grpc.type.Resolution resolution = 4;
+    int32 scenario = 5;
+    bool return_datasets = 6;
+}
+
+message SimulationResponse {}