ortools.math_opt.python.solver_resources

 1#!/usr/bin/env python3
 2# Copyright 2010-2025 Google LLC
 3# Licensed under the Apache License, Version 2.0 (the "License");
 4# you may not use this file except in compliance with the License.
 5# You may obtain a copy of the License at
 6#
 7#     http://www.apache.org/licenses/LICENSE-2.0
 8#
 9# Unless required by applicable law or agreed to in writing, software
10# distributed under the License is distributed on an "AS IS" BASIS,
11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12# See the License for the specific language governing permissions and
13# limitations under the License.
14
15"""Configures solver resources."""
16
17import dataclasses
18from typing import Optional
19
20from ortools.math_opt import rpc_pb2
21
22
23@dataclasses.dataclass
24class SolverResources:
25    """The hints on the resources a remote solve is expected to use.
26
27    These parameters are hints and may be ignored by the remote server (in
28    particular in case of solve in a local subprocess, for example).
29
30    When using remote_solve() and remote_compute_infeasible_subsystem(), these
31    hints are mostly optional as some defaults will be computed based on the other
32    parameters.
33
34    When using remote_streaming_solve() these hints are used to dimension the
35    resources available during the execution of every action; thus it is
36    recommended to set them.
37
38    MOE:begin_intracomment_strip
39
40    The go/uoss server will use these parameters to do a bin-packing of all
41    requests. Parameter cpu is a soft-limit, the solve may still be able to use
42    more CPUs.  The ram parameter is an hard-limit, an out-of-memory error will
43    occur if the solve attempts to use more memory.
44
45    MOE:end_intracomment_strip
46
47    Attributes:
48      cpu: The number of solver threads that are expected to actually execute in
49        parallel. Must be finite and >0.0.  For example a value of 3.0 means that
50        if the solver has 5 threads that can execute we expect at least 3 of these
51        threads to be scheduled in parallel for any given time slice of the
52        operating system scheduler.  A fractional value indicates that we don't
53        expect the operating system to constantly schedule the solver's work. For
54        example with 0.5 we would expect the solver's threads to be scheduled half
55        the time.  This parameter is usually used in conjunction with
56        SolveParameters.threads. For some solvers like Gurobi it makes sense to
57        use SolverResources.cpu = SolveParameters.threads. For other solvers like
58        CP-SAT, it may makes sense to use a value lower than the number of threads
59        as not all threads may be ready to be scheduled at the same time. It is
60        better to consult each solver documentation to set this parameter.  Note
61        that if the SolveParameters.threads is not set then this parameter should
62        also be left unset.
63      ram: The limit of RAM for the solve in bytes. Must be finite and >=1.0 (even
64        though it should in practice be much larger).
65    """
66
67    cpu: Optional[float] = None
68    ram: Optional[float] = None
69
70    def to_proto(self) -> rpc_pb2.SolverResourcesProto:
71        return rpc_pb2.SolverResourcesProto(cpu=self.cpu, ram=self.ram)