generalized-maxflow 0.3.0__tar.gz → 0.4.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. {generalized_maxflow-0.3.0 → generalized_maxflow-0.4.0}/CMakeLists.txt +3 -3
  2. {generalized_maxflow-0.3.0 → generalized_maxflow-0.4.0}/PKG-INFO +46 -8
  3. {generalized_maxflow-0.3.0 → generalized_maxflow-0.4.0}/README.md +45 -7
  4. generalized_maxflow-0.4.0/bindings/c/capi.cpp +133 -0
  5. {generalized_maxflow-0.3.0 → generalized_maxflow-0.4.0}/bindings/wasm/index.d.ts +23 -0
  6. generalized_maxflow-0.4.0/bindings/wasm/index.mjs +119 -0
  7. {generalized_maxflow-0.3.0 → generalized_maxflow-0.4.0}/bindings/wasm/package.json +1 -1
  8. {generalized_maxflow-0.3.0 → generalized_maxflow-0.4.0}/bindings/wasm/test_node.mjs +12 -0
  9. {generalized_maxflow-0.3.0 → generalized_maxflow-0.4.0}/pyproject.toml +1 -1
  10. {generalized_maxflow-0.3.0 → generalized_maxflow-0.4.0}/python/gmaxflow/__init__.py +40 -0
  11. generalized_maxflow-0.4.0/python/gmaxflow/_native.py +136 -0
  12. {generalized_maxflow-0.3.0 → generalized_maxflow-0.4.0}/src/solver.cpp +1 -1
  13. {generalized_maxflow-0.3.0 → generalized_maxflow-0.4.0}/tests/test_python.py +51 -0
  14. generalized_maxflow-0.4.0/tools/bench_arrays.py +73 -0
  15. generalized_maxflow-0.3.0/bindings/c/capi.cpp +0 -71
  16. generalized_maxflow-0.3.0/bindings/wasm/index.mjs +0 -70
  17. generalized_maxflow-0.3.0/python/gmaxflow/_native.py +0 -75
  18. {generalized_maxflow-0.3.0 → generalized_maxflow-0.4.0}/.gitattributes +0 -0
  19. {generalized_maxflow-0.3.0 → generalized_maxflow-0.4.0}/.gitignore +0 -0
  20. {generalized_maxflow-0.3.0 → generalized_maxflow-0.4.0}/LICENSE +0 -0
  21. {generalized_maxflow-0.3.0 → generalized_maxflow-0.4.0}/bindings/wasm/build.sh +0 -0
  22. {generalized_maxflow-0.3.0 → generalized_maxflow-0.4.0}/examples/currency_arbitrage.json +0 -0
  23. {generalized_maxflow-0.3.0 → generalized_maxflow-0.4.0}/examples/power_grid.json +0 -0
  24. {generalized_maxflow-0.3.0 → generalized_maxflow-0.4.0}/examples/rerouting.json +0 -0
  25. {generalized_maxflow-0.3.0 → generalized_maxflow-0.4.0}/include/gmf/gmf.hpp +0 -0
  26. {generalized_maxflow-0.3.0 → generalized_maxflow-0.4.0}/include/gmf/json.hpp +0 -0
  27. {generalized_maxflow-0.3.0 → generalized_maxflow-0.4.0}/python/gmaxflow/__main__.py +0 -0
  28. {generalized_maxflow-0.3.0 → generalized_maxflow-0.4.0}/python/gmaxflow/py.typed +0 -0
  29. {generalized_maxflow-0.3.0 → generalized_maxflow-0.4.0}/src/api.cpp +0 -0
  30. {generalized_maxflow-0.3.0 → generalized_maxflow-0.4.0}/src/cli_main.cpp +0 -0
  31. {generalized_maxflow-0.3.0 → generalized_maxflow-0.4.0}/src/json.cpp +0 -0
  32. {generalized_maxflow-0.3.0 → generalized_maxflow-0.4.0}/tests/harness.hpp +0 -0
  33. {generalized_maxflow-0.3.0 → generalized_maxflow-0.4.0}/tests/reference.hpp +0 -0
  34. {generalized_maxflow-0.3.0 → generalized_maxflow-0.4.0}/tests/test_api.cpp +0 -0
  35. {generalized_maxflow-0.3.0 → generalized_maxflow-0.4.0}/tests/test_json.cpp +0 -0
  36. {generalized_maxflow-0.3.0 → generalized_maxflow-0.4.0}/tests/test_main.cpp +0 -0
  37. {generalized_maxflow-0.3.0 → generalized_maxflow-0.4.0}/tests/test_regression.cpp +0 -0
  38. {generalized_maxflow-0.3.0 → generalized_maxflow-0.4.0}/tests/test_solver.cpp +0 -0
  39. {generalized_maxflow-0.3.0 → generalized_maxflow-0.4.0}/tools/bench.cpp +0 -0
  40. {generalized_maxflow-0.3.0 → generalized_maxflow-0.4.0}/tools/gap_probe.py +0 -0
  41. {generalized_maxflow-0.3.0 → generalized_maxflow-0.4.0}/tools/lp_check.py +0 -0
@@ -1,7 +1,7 @@
1
1
  cmake_minimum_required(VERSION 3.18)
2
2
 
3
3
  project(generalized-maxflow
4
- VERSION 0.3.0
4
+ VERSION 0.4.0
5
5
  DESCRIPTION "Generalized maximum flow: maximum flow with per-edge gain multipliers"
6
6
  LANGUAGES CXX)
7
7
 
@@ -134,8 +134,8 @@ if(EMSCRIPTEN)
134
134
  "-sEXPORT_ES6=1"
135
135
  "-sEXPORT_NAME=createGmaxflow"
136
136
  "-sALLOW_MEMORY_GROWTH=1"
137
- "-sEXPORTED_FUNCTIONS=['_gmf_solve_json','_gmf_solve_json_n','_gmf_free','_gmf_version','_malloc','_free']"
138
- "-sEXPORTED_RUNTIME_METHODS=['ccall','cwrap','UTF8ToString','stringToUTF8','lengthBytesUTF8']"
137
+ "-sEXPORTED_FUNCTIONS=['_gmf_solve_json','_gmf_solve_json_n','_gmf_solve_arrays','_gmf_solve_arrays_flows','_gmf_free','_gmf_version','_malloc','_free']"
138
+ "-sEXPORTED_RUNTIME_METHODS=['ccall','cwrap','UTF8ToString','stringToUTF8','lengthBytesUTF8','HEAP32','HEAPF64']"
139
139
  "-sENVIRONMENT=web,worker,node"
140
140
  "--no-entry")
141
141
  endif()
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.1
2
2
  Name: generalized-maxflow
3
- Version: 0.3.0
3
+ Version: 0.4.0
4
4
  Summary: Generalized maximum flow: maximum flow with per-edge gain multipliers
5
5
  Keywords: maximum-flow,generalized-flow,network-flow,graph,optimization,lossy-network
6
6
  Author: wesboyt
@@ -161,6 +161,44 @@ const answer = solver.solve(graph); // takes and returns plain objects
161
161
  console.log(answer.max_flow);
162
162
  ```
163
163
 
164
+ ### Arrays straight from memory
165
+
166
+ For many small solves — a regret label per decision, a lattice per window —
167
+ the JSON round trip costs more than the solve. `max_flow_arrays` and
168
+ `solveArrays` take the graph as parallel arrays, read in place from memory the
169
+ caller already holds (numpy / `array.array` buffers in Python, typed arrays
170
+ copied straight into the WebAssembly heap in JavaScript), and return numbers:
171
+
172
+ ```python
173
+ import numpy as np, gmaxflow
174
+
175
+ frm = np.array([0, 1], np.int32); to = np.array([1, 2], np.int32)
176
+ cap = np.array([10.0, 5.0]); mul = np.array([1.0, 2.0]) # cap < 0 = unbounded
177
+ flow = np.zeros(2) # optional, filled in place
178
+ gmaxflow.max_flow_arrays(3, 0, 2, frm, to, cap, mul, edge_flow=flow) # 10.0; flow == [5, 5]
179
+ ```
180
+
181
+ ```js
182
+ const r = solver.solveArrays(3, 0, 2, Int32Array.of(0, 1), Int32Array.of(1, 2),
183
+ Float64Array.of(10, 5), Float64Array.of(1, 2), { edgeFlow: true });
184
+ // r.maxFlow === 10, r.edgeFlow is a Float64Array
185
+ ```
186
+
187
+ The C ABI underneath is `gmf_solve_arrays_flows` (and `gmf_solve_arrays`
188
+ without flows) in `bindings/c/capi.cpp`. Paths are not recorded on this route.
189
+ On time-expanded trading lattices (`python tools/bench_arrays.py`, one core,
190
+ same answer to 1e-9 on every instance):
191
+
192
+ | layers | edges | JSON | arrays | speed-up |
193
+ | --- | --- | --- | --- | --- |
194
+ | 4 | 49 | 1.14 ms | 0.057 ms | **20x** |
195
+ | 16 | 193 | 3.82 ms | 0.118 ms | **32x** |
196
+ | 64 | 769 | 18.2 ms | 1.27 ms | **14x** |
197
+ | 256 | 3 073 | 85.8 ms | 17.8 ms | **4.8x** |
198
+
199
+ The gain is largest where the solve is small and the encoding dominates; on
200
+ large graphs the solve itself takes over.
201
+
164
202
  Command line (reads a file or stdin, writes JSON):
165
203
 
166
204
  ```bash
@@ -241,7 +279,7 @@ breakdown by phase and the solver's own memory footprint.
241
279
 
242
280
  Let $`G=(V,E)`$ be a directed graph with a source $`s`$ and a sink $`t`$. Each arc
243
281
  $`e\in E`$ has a capacity $`u(e)\in[0,\infty]`$ and a **multiplier** (or gain)
244
- $`\gamma(e)>0`$. A *generalized flow* is $`f:E\to\mathbb{R}`$ with
282
+ $`\gamma(e)\gt 0`$. A *generalized flow* is $`f:E\to\mathbb{R}`$ with
245
283
 
246
284
  ```math
247
285
  0 \le f(e) \le u(e) \quad \forall e \in E,
@@ -264,7 +302,7 @@ linear program, which is how `tools/lp_check.py` verifies the solver
264
302
  independently.
265
303
 
266
304
  For a path or cycle $`P`$ write $`\gamma(P)=\prod_{e\in P}\gamma(e)`$. A cycle $`C`$
267
- with $`\gamma(C)>1`$ is **flow-generating**: traversing it returns more than was
305
+ with $`\gamma(C)\gt 1`$ is **flow-generating**: traversing it returns more than was
268
306
  put in.
269
307
 
270
308
  ## 2. The residual network
@@ -293,25 +331,25 @@ first augmentation no search may assume all multipliers are below 1.
293
331
  ## 3. The bottleneck obeys the chain rule
294
332
 
295
333
  Along a path $`P=(a_1,\dots,a_k)`$ the amount entering $`a_i`$ when $`x`$ units enter
296
- $`a_1`$ is $`x\prod_{j<i}\gamma(a_j)`$. The largest feasible $`x`$ is therefore
334
+ $`a_1`$ is $`x\prod_{j\lt i}\gamma(a_j)`$. The largest feasible $`x`$ is therefore
297
335
 
298
336
  ```math
299
- \delta(P) \;=\; \min_{1\le i\le k} \; \frac{r(a_i)}{\prod_{j<i}\gamma(a_j)},
337
+ \delta(P) \;=\; \min_{1\le i\le k} \; \frac{r(a_i)}{\prod_{j\lt i}\gamma(a_j)},
300
338
  ```
301
339
 
302
340
  and the arc attaining the minimum is the **constricting edge**. It is not the
303
341
  arc of smallest residual capacity: gain downstream of a constriction counts.
304
342
 
305
343
  When a walk uses an arc in both directions — a cycle one way and the route
306
- carrying its excess the other — the two uses *cancel* rather than compete.
344
+ carrying its excess the other — the two use *cancel* rather than compete.
307
345
  Writing $`\alpha`$ for the total coefficient on the forward arc of an edge and
308
346
  $`\beta`$ for that on its backward arc, the net change to that edge's flow per
309
347
  unit $`x`$ is $`\nu = \alpha - \beta/\gamma`$, and the limit is
310
348
 
311
349
  ```math
312
350
  x \;\le\; \begin{cases}
313
- r(e)\,/\,\nu & \nu > 0,\\[2pt]
314
- r(e^{-1})\,/\,(-\nu\,\gamma) & \nu < 0,\\[2pt]
351
+ r(e)\,/\,\nu & \nu \gt 0,\\[2pt]
352
+ r(e^{-1})\,/\,(-\nu\,\gamma) & \nu \lt 0,\\[2pt]
315
353
  \infty & \nu = 0.
316
354
  \end{cases}
317
355
  ```
@@ -117,6 +117,44 @@ const answer = solver.solve(graph); // takes and returns plain objects
117
117
  console.log(answer.max_flow);
118
118
  ```
119
119
 
120
+ ### Arrays straight from memory
121
+
122
+ For many small solves — a regret label per decision, a lattice per window —
123
+ the JSON round trip costs more than the solve. `max_flow_arrays` and
124
+ `solveArrays` take the graph as parallel arrays, read in place from memory the
125
+ caller already holds (numpy / `array.array` buffers in Python, typed arrays
126
+ copied straight into the WebAssembly heap in JavaScript), and return numbers:
127
+
128
+ ```python
129
+ import numpy as np, gmaxflow
130
+
131
+ frm = np.array([0, 1], np.int32); to = np.array([1, 2], np.int32)
132
+ cap = np.array([10.0, 5.0]); mul = np.array([1.0, 2.0]) # cap < 0 = unbounded
133
+ flow = np.zeros(2) # optional, filled in place
134
+ gmaxflow.max_flow_arrays(3, 0, 2, frm, to, cap, mul, edge_flow=flow) # 10.0; flow == [5, 5]
135
+ ```
136
+
137
+ ```js
138
+ const r = solver.solveArrays(3, 0, 2, Int32Array.of(0, 1), Int32Array.of(1, 2),
139
+ Float64Array.of(10, 5), Float64Array.of(1, 2), { edgeFlow: true });
140
+ // r.maxFlow === 10, r.edgeFlow is a Float64Array
141
+ ```
142
+
143
+ The C ABI underneath is `gmf_solve_arrays_flows` (and `gmf_solve_arrays`
144
+ without flows) in `bindings/c/capi.cpp`. Paths are not recorded on this route.
145
+ On time-expanded trading lattices (`python tools/bench_arrays.py`, one core,
146
+ same answer to 1e-9 on every instance):
147
+
148
+ | layers | edges | JSON | arrays | speed-up |
149
+ | --- | --- | --- | --- | --- |
150
+ | 4 | 49 | 1.14 ms | 0.057 ms | **20x** |
151
+ | 16 | 193 | 3.82 ms | 0.118 ms | **32x** |
152
+ | 64 | 769 | 18.2 ms | 1.27 ms | **14x** |
153
+ | 256 | 3 073 | 85.8 ms | 17.8 ms | **4.8x** |
154
+
155
+ The gain is largest where the solve is small and the encoding dominates; on
156
+ large graphs the solve itself takes over.
157
+
120
158
  Command line (reads a file or stdin, writes JSON):
121
159
 
122
160
  ```bash
@@ -197,7 +235,7 @@ breakdown by phase and the solver's own memory footprint.
197
235
 
198
236
  Let $`G=(V,E)`$ be a directed graph with a source $`s`$ and a sink $`t`$. Each arc
199
237
  $`e\in E`$ has a capacity $`u(e)\in[0,\infty]`$ and a **multiplier** (or gain)
200
- $`\gamma(e)>0`$. A *generalized flow* is $`f:E\to\mathbb{R}`$ with
238
+ $`\gamma(e)\gt 0`$. A *generalized flow* is $`f:E\to\mathbb{R}`$ with
201
239
 
202
240
  ```math
203
241
  0 \le f(e) \le u(e) \quad \forall e \in E,
@@ -220,7 +258,7 @@ linear program, which is how `tools/lp_check.py` verifies the solver
220
258
  independently.
221
259
 
222
260
  For a path or cycle $`P`$ write $`\gamma(P)=\prod_{e\in P}\gamma(e)`$. A cycle $`C`$
223
- with $`\gamma(C)>1`$ is **flow-generating**: traversing it returns more than was
261
+ with $`\gamma(C)\gt 1`$ is **flow-generating**: traversing it returns more than was
224
262
  put in.
225
263
 
226
264
  ## 2. The residual network
@@ -249,25 +287,25 @@ first augmentation no search may assume all multipliers are below 1.
249
287
  ## 3. The bottleneck obeys the chain rule
250
288
 
251
289
  Along a path $`P=(a_1,\dots,a_k)`$ the amount entering $`a_i`$ when $`x`$ units enter
252
- $`a_1`$ is $`x\prod_{j<i}\gamma(a_j)`$. The largest feasible $`x`$ is therefore
290
+ $`a_1`$ is $`x\prod_{j\lt i}\gamma(a_j)`$. The largest feasible $`x`$ is therefore
253
291
 
254
292
  ```math
255
- \delta(P) \;=\; \min_{1\le i\le k} \; \frac{r(a_i)}{\prod_{j<i}\gamma(a_j)},
293
+ \delta(P) \;=\; \min_{1\le i\le k} \; \frac{r(a_i)}{\prod_{j\lt i}\gamma(a_j)},
256
294
  ```
257
295
 
258
296
  and the arc attaining the minimum is the **constricting edge**. It is not the
259
297
  arc of smallest residual capacity: gain downstream of a constriction counts.
260
298
 
261
299
  When a walk uses an arc in both directions — a cycle one way and the route
262
- carrying its excess the other — the two uses *cancel* rather than compete.
300
+ carrying its excess the other — the two use *cancel* rather than compete.
263
301
  Writing $`\alpha`$ for the total coefficient on the forward arc of an edge and
264
302
  $`\beta`$ for that on its backward arc, the net change to that edge's flow per
265
303
  unit $`x`$ is $`\nu = \alpha - \beta/\gamma`$, and the limit is
266
304
 
267
305
  ```math
268
306
  x \;\le\; \begin{cases}
269
- r(e)\,/\,\nu & \nu > 0,\\[2pt]
270
- r(e^{-1})\,/\,(-\nu\,\gamma) & \nu < 0,\\[2pt]
307
+ r(e)\,/\,\nu & \nu \gt 0,\\[2pt]
308
+ r(e^{-1})\,/\,(-\nu\,\gamma) & \nu \lt 0,\\[2pt]
271
309
  \infty & \nu = 0.
272
310
  \end{cases}
273
311
  ```
@@ -0,0 +1,133 @@
1
+ // The plain C ABI: the JSON interface, plus an array interface for callers
2
+ // that already hold the graph in memory, with no C++ or Python types at the
3
+ // boundary. The Python package loads it with ctypes and the
4
+ // WebAssembly build exports it, so neither links against an interpreter -- one
5
+ // wheel per OS and CPU serves every Python version.
6
+ //
7
+ // Strings cross the boundary as UTF-8. The caller owns what gmf_solve_json
8
+ // returns and frees it with gmf_free; a null return means memory ran out.
9
+ #include <cstddef>
10
+ #include <cstdlib>
11
+ #include <cstring>
12
+ #include <limits>
13
+ #include <new>
14
+ #include <string>
15
+
16
+ #include "gmf/gmf.hpp"
17
+
18
+ #if defined(__EMSCRIPTEN__)
19
+ #include <emscripten/emscripten.h>
20
+ #define GMF_EXPORT EMSCRIPTEN_KEEPALIVE
21
+ #elif defined(_WIN32)
22
+ #define GMF_EXPORT __declspec(dllexport)
23
+ #else
24
+ #define GMF_EXPORT __attribute__((visibility("default")))
25
+ #endif
26
+
27
+ namespace {
28
+
29
+ char* duplicate(const std::string& text, std::size_t* size) {
30
+ char* buffer = static_cast<char*>(std::malloc(text.size() + 1));
31
+ if (buffer == nullptr) return nullptr;
32
+ std::memcpy(buffer, text.c_str(), text.size() + 1);
33
+ if (size != nullptr) *size = text.size();
34
+ return buffer;
35
+ }
36
+
37
+ char* solve(const std::string& request, std::size_t* size) {
38
+ try {
39
+ return duplicate(gmf::solve_json(request), size);
40
+ } catch (const std::bad_alloc&) {
41
+ return nullptr;
42
+ } catch (...) {
43
+ return duplicate("{\"status\":\"invalid_input\",\"error\":\"unknown error\"}", size);
44
+ }
45
+ }
46
+
47
+ } // namespace
48
+
49
+ extern "C" {
50
+
51
+ // A NUL-terminated request.
52
+ GMF_EXPORT char* gmf_solve_json(const char* request) {
53
+ if (request == nullptr) {
54
+ return duplicate("{\"status\":\"invalid_input\",\"error\":\"no request\"}", nullptr);
55
+ }
56
+ return solve(std::string(request), nullptr);
57
+ }
58
+
59
+ // A request of known length, which may hold NUL bytes; the answer's length is
60
+ // written to *answer_size when it is not null.
61
+ GMF_EXPORT char* gmf_solve_json_n(const char* request, std::size_t request_size,
62
+ std::size_t* answer_size) {
63
+ if (request == nullptr && request_size > 0) {
64
+ return duplicate("{\"status\":\"invalid_input\",\"error\":\"no request\"}", answer_size);
65
+ }
66
+ return solve(std::string(request == nullptr ? "" : request, request_size), answer_size);
67
+ }
68
+
69
+ // Arrays in, numbers out: no JSON on either side, for callers that solve many
70
+ // graphs from memory they already hold (numpy arrays, typed arrays in a
71
+ // WebAssembly heap). Edge e runs from[e] -> to[e] with capacity[e] and
72
+ // multiplier[e]; a capacity < 0 (or +inf) means unbounded. Paths are not
73
+ // recorded.
74
+ //
75
+ // *max_flow, when not null, receives the flow delivered at the sink;
76
+ // edge_flow, when not null, must hold num_edges doubles and receives the units
77
+ // entering each edge (delivered = edge_flow[e] * multiplier[e]).
78
+ //
79
+ // Returns 0 when the answer is certified optimal, 1 for any other solver status
80
+ // (the outputs are still written), 2 for a malformed problem (bad node id,
81
+ // negative multiplier, ...), 3 when memory ran out.
82
+ GMF_EXPORT int gmf_solve_arrays_flows(int num_nodes, int source, int sink, int num_edges,
83
+ const int* from, const int* to, const double* capacity,
84
+ const double* multiplier, double* max_flow,
85
+ double* edge_flow) {
86
+ try {
87
+ if (num_edges < 0 || (num_edges > 0 && (from == nullptr || to == nullptr ||
88
+ capacity == nullptr || multiplier == nullptr))) {
89
+ return 2;
90
+ }
91
+ gmf::Problem problem;
92
+ problem.num_nodes = num_nodes;
93
+ problem.source = source;
94
+ problem.sink = sink;
95
+ problem.edges.resize(static_cast<std::size_t>(num_edges));
96
+ for (int e = 0; e < num_edges; ++e) {
97
+ gmf::EdgeInput& edge = problem.edges[static_cast<std::size_t>(e)];
98
+ edge.from = from[e];
99
+ edge.to = to[e];
100
+ edge.capacity = capacity[e] < 0 ? std::numeric_limits<double>::infinity() : capacity[e];
101
+ edge.multiplier = multiplier[e];
102
+ }
103
+ gmf::Options options;
104
+ options.collect_paths = false;
105
+ const gmf::Result result = gmf::solve(problem, options);
106
+ if (max_flow != nullptr) *max_flow = result.max_flow;
107
+ if (edge_flow != nullptr) {
108
+ for (int e = 0; e < num_edges; ++e) {
109
+ const std::size_t i = static_cast<std::size_t>(e);
110
+ edge_flow[e] = i < result.edge_flow.size() ? result.edge_flow[i] : 0.0;
111
+ }
112
+ }
113
+ return result.optimal ? 0 : 1;
114
+ } catch (const std::bad_alloc&) {
115
+ return 3;
116
+ } catch (...) {
117
+ return 2;
118
+ }
119
+ }
120
+
121
+ // The same without per-edge flows.
122
+ GMF_EXPORT int gmf_solve_arrays(int num_nodes, int source, int sink, int num_edges,
123
+ const int* from, const int* to, const double* capacity,
124
+ const double* multiplier, double* max_flow) {
125
+ return gmf_solve_arrays_flows(num_nodes, source, sink, num_edges, from, to, capacity,
126
+ multiplier, max_flow, nullptr);
127
+ }
128
+
129
+ GMF_EXPORT void gmf_free(char* buffer) { std::free(buffer); }
130
+
131
+ GMF_EXPORT const char* gmf_version() { return gmf::version(); }
132
+
133
+ } // extern "C"
@@ -116,6 +116,15 @@ export interface Graph {
116
116
  options?: Options;
117
117
  }
118
118
 
119
+ export interface ArraysAnswer {
120
+ /** 0 optimal, 1 not certified, 2 malformed graph, 3 out of memory. */
121
+ status: 0 | 1 | 2 | 3;
122
+ optimal: boolean;
123
+ maxFlow: number;
124
+ /** Units entering each edge, when requested. */
125
+ edgeFlow?: Float64Array;
126
+ }
127
+
119
128
  export interface Solver {
120
129
  /** Solves a graph object (or JSON text) and returns the answer object. */
121
130
  solve(graph: Graph | string): Answer;
@@ -123,6 +132,20 @@ export interface Solver {
123
132
  solveText(request: string): string;
124
133
  /** The flow delivered at the sink; Infinity when unbounded. */
125
134
  maxFlow(graph: Graph | string): number;
135
+ /**
136
+ * Solves a graph held as parallel arrays, copied straight into the
137
+ * WebAssembly heap with no JSON. A capacity < 0 or Infinity is unbounded.
138
+ */
139
+ solveArrays(
140
+ numNodes: number,
141
+ source: number,
142
+ sink: number,
143
+ from: ArrayLike<number>,
144
+ to: ArrayLike<number>,
145
+ capacity: ArrayLike<number>,
146
+ multiplier: ArrayLike<number>,
147
+ options?: { edgeFlow?: boolean },
148
+ ): ArraysAnswer;
126
149
  version(): string;
127
150
  /** The underlying Emscripten runtime. */
128
151
  runtime: unknown;
@@ -0,0 +1,119 @@
1
+ // Generalized maximum flow, compiled to WebAssembly.
2
+ //
3
+ // import createSolver from "generalized-maxflow";
4
+ // const solver = await createSolver();
5
+ // console.log(solver.solve(graph).max_flow);
6
+ //
7
+ // The graph format is documented in the project README. Strings cross into
8
+ // WebAssembly as UTF-8; the buffer the solver returns is freed here.
9
+ import createGmaxflow from "./gmaxflow.js";
10
+
11
+ /**
12
+ * Loads the WebAssembly module and returns a solver bound to it.
13
+ * @param {object} [moduleOptions] passed through to the Emscripten runtime
14
+ */
15
+ export default async function createSolver(moduleOptions) {
16
+ const runtime = await createGmaxflow(moduleOptions);
17
+
18
+ const solveJson = runtime.cwrap("gmf_solve_json", "number", ["string"]);
19
+ const freeBuffer = runtime.cwrap("gmf_free", null, ["number"]);
20
+ const readVersion = runtime.cwrap("gmf_version", "string", []);
21
+ const solveArraysRaw = runtime.cwrap("gmf_solve_arrays_flows", "number", [
22
+ "number", "number", "number", "number",
23
+ "number", "number", "number", "number", "number", "number",
24
+ ]);
25
+
26
+ /**
27
+ * Solves a problem given as JSON text and returns the answer as JSON text.
28
+ * @param {string} request
29
+ * @returns {string}
30
+ */
31
+ function solveText(request) {
32
+ if (typeof request !== "string") {
33
+ throw new TypeError("solveText expects JSON text");
34
+ }
35
+ const pointer = solveJson(request);
36
+ if (!pointer) throw new Error("the solver could not allocate its answer");
37
+ try {
38
+ return runtime.UTF8ToString(pointer);
39
+ } finally {
40
+ freeBuffer(pointer);
41
+ }
42
+ }
43
+
44
+ /**
45
+ * Solves a problem given as an object (or JSON text) and returns the answer
46
+ * as an object. Throws when the graph is rejected.
47
+ * @param {object|string} graph
48
+ */
49
+ function solve(graph) {
50
+ const request = typeof graph === "string" ? graph : JSON.stringify(graph);
51
+ const answer = JSON.parse(solveText(request));
52
+ if (answer.status === "invalid_input") {
53
+ throw new Error(`generalized-maxflow: ${answer.error}`);
54
+ }
55
+ return answer;
56
+ }
57
+
58
+ /**
59
+ * The maximum flow delivered at the sink. Infinity when unbounded.
60
+ * @param {object|string} graph
61
+ * @returns {number}
62
+ */
63
+ function maxFlow(graph) {
64
+ return solve(graph).max_flow;
65
+ }
66
+
67
+ /**
68
+ * Solves a graph held as parallel typed arrays, copied straight into the
69
+ * WebAssembly heap: no JSON on either side. Edge e runs from[e] -> to[e];
70
+ * a capacity < 0 or Infinity is unbounded. Returns { status, optimal,
71
+ * maxFlow, edgeFlow } where edgeFlow (a Float64Array, only when
72
+ * options.edgeFlow is true) holds the units entering each edge.
73
+ * status: 0 optimal, 1 not certified, 2 malformed graph, 3 out of memory.
74
+ * @param {number} numNodes
75
+ * @param {number} source
76
+ * @param {number} sink
77
+ * @param {ArrayLike<number>} from
78
+ * @param {ArrayLike<number>} to
79
+ * @param {ArrayLike<number>} capacity
80
+ * @param {ArrayLike<number>} multiplier
81
+ * @param {{edgeFlow?: boolean}} [options]
82
+ */
83
+ function solveArrays(numNodes, source, sink, from, to, capacity, multiplier, options = {}) {
84
+ const m = from.length;
85
+ if (to.length !== m || capacity.length !== m || multiplier.length !== m) {
86
+ throw new RangeError("from, to, capacity and multiplier must have the same length");
87
+ }
88
+ const n = Math.max(m, 1);
89
+ const fromPtr = runtime._malloc(4 * n);
90
+ const toPtr = runtime._malloc(4 * n);
91
+ const capPtr = runtime._malloc(8 * n);
92
+ const mulPtr = runtime._malloc(8 * n);
93
+ const outPtr = runtime._malloc(8);
94
+ const flowPtr = options.edgeFlow ? runtime._malloc(8 * n) : 0;
95
+ try {
96
+ // Views are taken after every malloc: a grown heap detaches older views.
97
+ runtime.HEAP32.set(from, fromPtr >> 2);
98
+ runtime.HEAP32.set(to, toPtr >> 2);
99
+ runtime.HEAPF64.set(Float64Array.from(capacity, (c) => (c === Infinity ? -1 : c)), capPtr >> 3);
100
+ runtime.HEAPF64.set(multiplier, mulPtr >> 3);
101
+ const status = solveArraysRaw(numNodes, source, sink, m, fromPtr, toPtr, capPtr, mulPtr,
102
+ outPtr, flowPtr);
103
+ const result = { status, optimal: status === 0, maxFlow: runtime.HEAPF64[outPtr >> 3] };
104
+ if (flowPtr) result.edgeFlow = runtime.HEAPF64.slice(flowPtr >> 3, (flowPtr >> 3) + m);
105
+ return result;
106
+ } finally {
107
+ for (const p of [fromPtr, toPtr, capPtr, mulPtr, outPtr, flowPtr]) if (p) runtime._free(p);
108
+ }
109
+ }
110
+
111
+ return {
112
+ solve,
113
+ solveText,
114
+ maxFlow,
115
+ solveArrays,
116
+ version: () => readVersion(),
117
+ runtime,
118
+ };
119
+ }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "generalized-maxflow",
3
- "version": "0.3.0",
3
+ "version": "0.4.0",
4
4
  "description": "Generalized maximum flow: maximum flow with per-edge gain multipliers, compiled to WebAssembly",
5
5
  "type": "module",
6
6
  "main": "./index.mjs",
@@ -86,4 +86,16 @@ const solver = await createSolver();
86
86
  assert.equal(JSON.parse(text).max_flow, 2);
87
87
  }
88
88
 
89
+
90
+ {
91
+ // The array interface agrees with the JSON one and reports edge flows.
92
+ const r = solver.solveArrays(3, 0, 2, Int32Array.of(0, 1), Int32Array.of(1, 2),
93
+ Float64Array.of(10, 5), Float64Array.of(1, 2), { edgeFlow: true });
94
+ assert.equal(r.status, 0);
95
+ assert.equal(r.maxFlow, 10);
96
+ assert.deepEqual(Array.from(r.edgeFlow), [5, 5]);
97
+ const bad = solver.solveArrays(2, 0, 1, [0], [7], [1], [1]);
98
+ assert.equal(bad.status, 2);
99
+ }
100
+
89
101
  console.log("wasm smoke test passed");
@@ -4,7 +4,7 @@ build-backend = "scikit_build_core.build"
4
4
 
5
5
  [project]
6
6
  name = "generalized-maxflow"
7
- version = "0.3.0"
7
+ version = "0.4.0"
8
8
  description = "Generalized maximum flow: maximum flow with per-edge gain multipliers"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.8"
@@ -35,6 +35,7 @@ __all__ = [
35
35
  "solve",
36
36
  "solve_json",
37
37
  "max_flow",
38
+ "max_flow_arrays",
38
39
  "version",
39
40
  "InvalidGraphError",
40
41
  "NotOptimalError",
@@ -128,6 +129,45 @@ def max_flow(graph: Graph, **options: Any) -> float:
128
129
  return float(solve(graph, **options)["max_flow"])
129
130
 
130
131
 
132
+ def max_flow_arrays(
133
+ num_nodes: int,
134
+ source: int,
135
+ sink: int,
136
+ frm: Any,
137
+ to: Any,
138
+ capacity: Any,
139
+ multiplier: Any,
140
+ *,
141
+ edge_flow: Any = None,
142
+ require_optimal: bool = True,
143
+ ) -> float:
144
+ """The maximum flow of a graph held as parallel arrays, with no JSON.
145
+
146
+ Edge ``e`` runs ``frm[e] -> to[e]`` with ``capacity[e]`` (negative or
147
+ ``inf`` = unbounded) and ``multiplier[e]``; nodes are ``0 .. num_nodes-1``.
148
+ Contiguous int32 / float64 buffers (numpy arrays, ``array.array('i')`` /
149
+ ``array.array('d')``) are read in place; anything else is copied once.
150
+ Pass a writable float64 buffer of ``len(frm)`` entries as `edge_flow` to
151
+ receive the units entering each edge.
152
+
153
+ This is the fast path for many small solves: on graphs of a few hundred
154
+ edges it skips the JSON encode, parse and answer that dominate `solve`.
155
+
156
+ Raises `InvalidGraphError` on a malformed graph, `NotOptimalError` (with an
157
+ empty ``answer``) when `require_optimal` and the answer is not certified.
158
+ """
159
+ status, value = _native.solve_arrays(
160
+ num_nodes, source, sink, frm, to, capacity, multiplier, edge_flow
161
+ )
162
+ if status == 2:
163
+ raise InvalidGraphError("invalid graph arrays")
164
+ if status == 3:
165
+ raise MemoryError("the solver ran out of memory")
166
+ if status == 1 and require_optimal:
167
+ raise NotOptimalError("the solver did not certify the answer", {"max_flow": value})
168
+ return float(value)
169
+
170
+
131
171
  def version() -> str:
132
172
  """The version of the native solver."""
133
173
  return _native.version()
@@ -0,0 +1,136 @@
1
+ """ctypes binding to the native solver. Internal; use the public functions.
2
+
3
+ The solver is a shared library with a plain C ABI, so it never links against
4
+ libpython: one wheel per OS and CPU serves every CPython, free-threaded builds
5
+ included, and PyPy. ctypes releases the GIL for the length of each call, so
6
+ other threads keep running while a large graph is solved.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import ctypes
12
+ import os
13
+ import sys
14
+
15
+ _HERE = os.path.dirname(os.path.abspath(__file__))
16
+ _ENV = "GMAXFLOW_LIB"
17
+
18
+
19
+ def _library_path() -> str:
20
+ """$GMAXFLOW_LIB if set, else the library inside the installed package."""
21
+ override = os.environ.get(_ENV)
22
+ if override:
23
+ return override
24
+ name = {"win32": "gmaxflow_core.dll", "darwin": "gmaxflow_core.dylib"}.get(
25
+ sys.platform, "gmaxflow_core.so"
26
+ )
27
+ return os.path.join(_HERE, "_native", name)
28
+
29
+
30
+ def _load() -> ctypes.CDLL:
31
+ path = _library_path()
32
+ if not os.path.exists(path):
33
+ raise ImportError(
34
+ "the gmaxflow native solver was not found (%s). Install a wheel "
35
+ "(`pip install generalized-maxflow`), or build from a checkout with "
36
+ "`pip install .`; a library built by hand with CMake can be named in "
37
+ "$%s." % (path, _ENV)
38
+ )
39
+ return ctypes.CDLL(path)
40
+
41
+
42
+ _lib = _load()
43
+
44
+ _lib.gmf_solve_json_n.restype = ctypes.c_void_p
45
+ _lib.gmf_solve_json_n.argtypes = [
46
+ ctypes.c_char_p,
47
+ ctypes.c_size_t,
48
+ ctypes.POINTER(ctypes.c_size_t),
49
+ ]
50
+ _lib.gmf_free.restype = None
51
+ _lib.gmf_free.argtypes = [ctypes.c_void_p]
52
+ _lib.gmf_version.restype = ctypes.c_char_p
53
+ _lib.gmf_version.argtypes = []
54
+
55
+ _INT_P = ctypes.POINTER(ctypes.c_int)
56
+ _DOUBLE_P = ctypes.POINTER(ctypes.c_double)
57
+ _HAS_ARRAYS = hasattr(_lib, "gmf_solve_arrays_flows")
58
+ if _HAS_ARRAYS:
59
+ _lib.gmf_solve_arrays_flows.restype = ctypes.c_int
60
+ _lib.gmf_solve_arrays_flows.argtypes = [
61
+ ctypes.c_int, ctypes.c_int, ctypes.c_int, ctypes.c_int,
62
+ _INT_P, _INT_P, _DOUBLE_P, _DOUBLE_P, _DOUBLE_P, _DOUBLE_P,
63
+ ]
64
+
65
+
66
+ def _as_c(values, ctype, count):
67
+ """A ctypes view of `values` without copying when it already is contiguous
68
+ memory of the right type (a numpy array, array.array, memoryview); else a
69
+ copy. Returns (pointer, keep-alive object)."""
70
+ try:
71
+ view = memoryview(values)
72
+ except TypeError:
73
+ view = None
74
+ if (
75
+ view is not None
76
+ and view.contiguous
77
+ and view.ndim == 1
78
+ and view.itemsize == ctypes.sizeof(ctype)
79
+ and view.format in (("i", "l") if ctype is ctypes.c_int else ("d",))
80
+ and len(view) == count
81
+ and not view.readonly
82
+ ):
83
+ buffer = (ctype * count).from_buffer(view)
84
+ return ctypes.cast(buffer, ctypes.POINTER(ctype)), (view, buffer)
85
+ copy = (ctype * count)(*values)
86
+ return ctypes.cast(copy, ctypes.POINTER(ctype)), copy
87
+
88
+
89
+ def solve_arrays(num_nodes, source, sink, frm, to, capacity, multiplier, edge_flow):
90
+ """Returns (status code, max flow). Writes per-edge flows into `edge_flow`
91
+ (a writable float64 buffer of len(frm)) when it is not None."""
92
+ if not _HAS_ARRAYS:
93
+ raise RuntimeError("the loaded native library predates gmf_solve_arrays_flows")
94
+ count = len(frm)
95
+ if not (len(to) == len(capacity) == len(multiplier) == count):
96
+ raise ValueError("from, to, capacity and multiplier must have the same length")
97
+ keep = []
98
+ pointers = []
99
+ for values, ctype in ((frm, ctypes.c_int), (to, ctypes.c_int),
100
+ (capacity, ctypes.c_double), (multiplier, ctypes.c_double)):
101
+ pointer, alive = _as_c(values, ctype, count)
102
+ pointers.append(pointer)
103
+ keep.append(alive)
104
+ flows = None
105
+ if edge_flow is not None:
106
+ flows, alive = _as_c(edge_flow, ctypes.c_double, count)
107
+ if not isinstance(alive, tuple):
108
+ raise ValueError("edge_flow must be a writable float64 buffer of len(from) entries")
109
+ keep.append(alive)
110
+ out = ctypes.c_double(0.0)
111
+ status = _lib.gmf_solve_arrays_flows(
112
+ int(num_nodes), int(source), int(sink), count, *pointers, ctypes.byref(out), flows
113
+ )
114
+ return status, out.value
115
+
116
+
117
+ def solve_json(request: str) -> str:
118
+ """Solve the JSON request and return the JSON answer."""
119
+ data = request.encode("utf-8")
120
+ size = ctypes.c_size_t(0)
121
+ answer = _lib.gmf_solve_json_n(data, len(data), ctypes.byref(size))
122
+ if not answer:
123
+ raise MemoryError("the solver ran out of memory")
124
+ try:
125
+ return ctypes.string_at(answer, size.value).decode("utf-8")
126
+ finally:
127
+ _lib.gmf_free(answer)
128
+
129
+
130
+ def version() -> str:
131
+ return _lib.gmf_version().decode("ascii")
132
+
133
+
134
+ def library_path() -> str:
135
+ """Where the loaded native library lives, for diagnostics."""
136
+ return _library_path()
@@ -1768,6 +1768,6 @@ Result solve(const Problem& problem, const Options& options) {
1768
1768
  return solver.run();
1769
1769
  }
1770
1770
 
1771
- const char* version() { return "0.3.0"; }
1771
+ const char* version() { return "0.4.0"; }
1772
1772
 
1773
1773
  } // namespace gmf
@@ -216,3 +216,54 @@ def test_the_installed_package_carries_its_own_native_library():
216
216
  package = os.path.normcase(os.path.dirname(os.path.abspath(gmaxflow.__file__)))
217
217
  assert not package.startswith(checkout), "imported the checkout, not the wheel"
218
218
  assert os.path.isfile(_native.library_path())
219
+
220
+
221
+ def test_the_array_interface_matches_the_json_one():
222
+ import array
223
+
224
+ frm = array.array("i", [0, 1, 0])
225
+ to = array.array("i", [1, 2, 2])
226
+ cap = array.array("d", [10.0, 5.0, 4.0])
227
+ mul = array.array("d", [1.0, 2.0, 0.5])
228
+ flows = array.array("d", [0.0, 0.0, 0.0])
229
+ got = gmaxflow.max_flow_arrays(3, 0, 2, frm, to, cap, mul, edge_flow=flows)
230
+ want = gmaxflow.max_flow({
231
+ "source": 0, "sink": 2,
232
+ "edges": [
233
+ {"from": 0, "to": 1, "capacity": 10, "multiplier": 1.0},
234
+ {"from": 1, "to": 2, "capacity": 5, "multiplier": 2.0},
235
+ {"from": 0, "to": 2, "capacity": 4, "multiplier": 0.5},
236
+ ],
237
+ })
238
+ assert got == pytest.approx(want) == pytest.approx(12.0)
239
+ assert list(flows) == pytest.approx([5.0, 5.0, 4.0])
240
+
241
+
242
+ def test_a_negative_capacity_is_unbounded_in_the_array_interface():
243
+ got = gmaxflow.max_flow_arrays(3, 0, 2, [0, 1], [1, 2], [-1.0, 5.0], [1.0, 2.0])
244
+ assert got == pytest.approx(10.0)
245
+
246
+
247
+ def test_the_array_interface_reports_edge_flows():
248
+ import array
249
+
250
+ out = array.array("d", [0.0, 0.0])
251
+ got = gmaxflow.max_flow_arrays(3, 0, 2, [0, 1], [1, 2], [10.0, 5.0], [1.0, 2.0], edge_flow=out)
252
+ assert got == pytest.approx(10.0)
253
+ assert list(out) == pytest.approx([5.0, 5.0])
254
+
255
+
256
+ def test_the_array_interface_reads_numpy_in_place():
257
+ np = pytest.importorskip("numpy")
258
+ frm = np.array([0, 1], np.int32)
259
+ to = np.array([1, 2], np.int32)
260
+ cap = np.array([3.0, 3.0])
261
+ mul = np.array([0.5, 4.0])
262
+ flows = np.zeros(2)
263
+ assert gmaxflow.max_flow_arrays(3, 0, 2, frm, to, cap, mul, edge_flow=flows) == pytest.approx(6.0)
264
+ assert flows.tolist() == pytest.approx([3.0, 1.5])
265
+
266
+
267
+ def test_the_array_interface_rejects_a_bad_node():
268
+ with pytest.raises(gmaxflow.InvalidGraphError):
269
+ gmaxflow.max_flow_arrays(2, 0, 1, [0], [9], [1.0], [1.0])
@@ -0,0 +1,73 @@
1
+ """Times gmaxflow.solve (JSON) against gmaxflow.max_flow_arrays on the same
2
+ time-expanded trading lattices: L layers of a cash node and a holding node,
3
+ five buy and five sell levels per layer, hold arcs between layers.
4
+
5
+ python tools/bench_arrays.py [--layers 10 40 160] [--repeat 200]
6
+ """
7
+ import argparse
8
+ import random
9
+ import time
10
+
11
+ import gmaxflow
12
+
13
+
14
+ def lattice(layers, seed):
15
+ rnd = random.Random(seed)
16
+ frm, to, cap, mul = [], [], [], []
17
+ s, t = 0, 1
18
+ cash = lambda j: 2 + 2 * j # noqa: E731
19
+ hold = lambda j: 3 + 2 * j # noqa: E731
20
+ frm.append(s); to.append(cash(0)); cap.append(100.0); mul.append(1.0)
21
+ mid = 0.5
22
+ for j in range(layers):
23
+ mid = min(0.95, max(0.05, mid + rnd.gauss(0, 0.02)))
24
+ for k in range(5):
25
+ ask, bid = mid + 0.01 * (k + 1), mid - 0.01 * (k + 1)
26
+ n = rnd.uniform(5, 50)
27
+ frm.append(cash(j)); to.append(hold(j)); cap.append(ask * n); mul.append(1 / (ask + 0.0175))
28
+ frm.append(hold(j)); to.append(cash(j)); cap.append(n); mul.append(bid - 0.0175)
29
+ nxt_c, nxt_h = (cash(j + 1), hold(j + 1)) if j + 1 < layers else (t, t)
30
+ frm += [cash(j), hold(j)]; to += [nxt_c, nxt_h]; cap += [-1.0, -1.0]
31
+ mul += [1.0, 1.0 if j + 1 < layers else (1.0 if rnd.random() < mid else 1e-9)]
32
+ return 2 + 2 * layers, s, t, frm, to, cap, mul
33
+
34
+
35
+ def as_json(n, s, t, frm, to, cap, mul):
36
+ return {"source": s, "sink": t, "nodes": list(range(n)), "options": {"collect_paths": False},
37
+ "edges": [{"from": a, "to": b, "capacity": (None if c < 0 else c), "multiplier": m}
38
+ for a, b, c, m in zip(frm, to, cap, mul)]}
39
+
40
+
41
+ def main():
42
+ ap = argparse.ArgumentParser()
43
+ ap.add_argument("--layers", type=int, nargs="+", default=[10, 40, 160])
44
+ ap.add_argument("--repeat", type=int, default=200)
45
+ a = ap.parse_args()
46
+ try:
47
+ import numpy as np
48
+ except ImportError:
49
+ np = None
50
+ print("layers edges json us/solve arrays us/solve speed-up")
51
+ for L in a.layers:
52
+ g = lattice(L, 7)
53
+ js = as_json(*g)
54
+ n, s, t, frm, to, cap, mul = g
55
+ if np is not None:
56
+ frm, to = np.array(frm, np.int32), np.array(to, np.int32)
57
+ cap, mul = np.array(cap), np.array(mul)
58
+ v1 = gmaxflow.solve(js)["max_flow"]
59
+ v2 = gmaxflow.max_flow_arrays(n, s, t, frm, to, cap, mul)
60
+ assert abs(v1 - v2) <= 1e-9 * max(1.0, abs(v1)), (v1, v2)
61
+ t0 = time.perf_counter()
62
+ for _ in range(a.repeat):
63
+ gmaxflow.solve(js)
64
+ tj = (time.perf_counter() - t0) / a.repeat
65
+ t0 = time.perf_counter()
66
+ for _ in range(a.repeat):
67
+ gmaxflow.max_flow_arrays(n, s, t, frm, to, cap, mul)
68
+ ta = (time.perf_counter() - t0) / a.repeat
69
+ print("%6d %6d %14.1f %16.1f %9.1fx" % (L, len(g[3]), tj * 1e6, ta * 1e6, tj / ta))
70
+
71
+
72
+ if __name__ == "__main__":
73
+ main()
@@ -1,71 +0,0 @@
1
- // The plain C ABI: the JSON interface, behind three functions with no C++ or
2
- // Python types at the boundary. The Python package loads it with ctypes and the
3
- // WebAssembly build exports it, so neither links against an interpreter -- one
4
- // wheel per OS and CPU serves every Python version.
5
- //
6
- // Strings cross the boundary as UTF-8. The caller owns what gmf_solve_json
7
- // returns and frees it with gmf_free; a null return means memory ran out.
8
- #include <cstddef>
9
- #include <cstdlib>
10
- #include <cstring>
11
- #include <new>
12
- #include <string>
13
-
14
- #include "gmf/gmf.hpp"
15
-
16
- #if defined(__EMSCRIPTEN__)
17
- #include <emscripten/emscripten.h>
18
- #define GMF_EXPORT EMSCRIPTEN_KEEPALIVE
19
- #elif defined(_WIN32)
20
- #define GMF_EXPORT __declspec(dllexport)
21
- #else
22
- #define GMF_EXPORT __attribute__((visibility("default")))
23
- #endif
24
-
25
- namespace {
26
-
27
- char* duplicate(const std::string& text, std::size_t* size) {
28
- char* buffer = static_cast<char*>(std::malloc(text.size() + 1));
29
- if (buffer == nullptr) return nullptr;
30
- std::memcpy(buffer, text.c_str(), text.size() + 1);
31
- if (size != nullptr) *size = text.size();
32
- return buffer;
33
- }
34
-
35
- char* solve(const std::string& request, std::size_t* size) {
36
- try {
37
- return duplicate(gmf::solve_json(request), size);
38
- } catch (const std::bad_alloc&) {
39
- return nullptr;
40
- } catch (...) {
41
- return duplicate("{\"status\":\"invalid_input\",\"error\":\"unknown error\"}", size);
42
- }
43
- }
44
-
45
- } // namespace
46
-
47
- extern "C" {
48
-
49
- // A NUL-terminated request.
50
- GMF_EXPORT char* gmf_solve_json(const char* request) {
51
- if (request == nullptr) {
52
- return duplicate("{\"status\":\"invalid_input\",\"error\":\"no request\"}", nullptr);
53
- }
54
- return solve(std::string(request), nullptr);
55
- }
56
-
57
- // A request of known length, which may hold NUL bytes; the answer's length is
58
- // written to *answer_size when it is not null.
59
- GMF_EXPORT char* gmf_solve_json_n(const char* request, std::size_t request_size,
60
- std::size_t* answer_size) {
61
- if (request == nullptr && request_size > 0) {
62
- return duplicate("{\"status\":\"invalid_input\",\"error\":\"no request\"}", answer_size);
63
- }
64
- return solve(std::string(request == nullptr ? "" : request, request_size), answer_size);
65
- }
66
-
67
- GMF_EXPORT void gmf_free(char* buffer) { std::free(buffer); }
68
-
69
- GMF_EXPORT const char* gmf_version() { return gmf::version(); }
70
-
71
- } // extern "C"
@@ -1,70 +0,0 @@
1
- // Generalized maximum flow, compiled to WebAssembly.
2
- //
3
- // import createSolver from "generalized-maxflow";
4
- // const solver = await createSolver();
5
- // console.log(solver.solve(graph).max_flow);
6
- //
7
- // The graph format is documented in the project README. Strings cross into
8
- // WebAssembly as UTF-8; the buffer the solver returns is freed here.
9
- import createGmaxflow from "./gmaxflow.js";
10
-
11
- /**
12
- * Loads the WebAssembly module and returns a solver bound to it.
13
- * @param {object} [moduleOptions] passed through to the Emscripten runtime
14
- */
15
- export default async function createSolver(moduleOptions) {
16
- const runtime = await createGmaxflow(moduleOptions);
17
-
18
- const solveJson = runtime.cwrap("gmf_solve_json", "number", ["string"]);
19
- const freeBuffer = runtime.cwrap("gmf_free", null, ["number"]);
20
- const readVersion = runtime.cwrap("gmf_version", "string", []);
21
-
22
- /**
23
- * Solves a problem given as JSON text and returns the answer as JSON text.
24
- * @param {string} request
25
- * @returns {string}
26
- */
27
- function solveText(request) {
28
- if (typeof request !== "string") {
29
- throw new TypeError("solveText expects JSON text");
30
- }
31
- const pointer = solveJson(request);
32
- if (!pointer) throw new Error("the solver could not allocate its answer");
33
- try {
34
- return runtime.UTF8ToString(pointer);
35
- } finally {
36
- freeBuffer(pointer);
37
- }
38
- }
39
-
40
- /**
41
- * Solves a problem given as an object (or JSON text) and returns the answer
42
- * as an object. Throws when the graph is rejected.
43
- * @param {object|string} graph
44
- */
45
- function solve(graph) {
46
- const request = typeof graph === "string" ? graph : JSON.stringify(graph);
47
- const answer = JSON.parse(solveText(request));
48
- if (answer.status === "invalid_input") {
49
- throw new Error(`generalized-maxflow: ${answer.error}`);
50
- }
51
- return answer;
52
- }
53
-
54
- /**
55
- * The maximum flow delivered at the sink. Infinity when unbounded.
56
- * @param {object|string} graph
57
- * @returns {number}
58
- */
59
- function maxFlow(graph) {
60
- return solve(graph).max_flow;
61
- }
62
-
63
- return {
64
- solve,
65
- solveText,
66
- maxFlow,
67
- version: () => readVersion(),
68
- runtime,
69
- };
70
- }
@@ -1,75 +0,0 @@
1
- """ctypes binding to the native solver. Internal; use the public functions.
2
-
3
- The solver is a shared library with a plain C ABI, so it never links against
4
- libpython: one wheel per OS and CPU serves every CPython, free-threaded builds
5
- included, and PyPy. ctypes releases the GIL for the length of each call, so
6
- other threads keep running while a large graph is solved.
7
- """
8
-
9
- from __future__ import annotations
10
-
11
- import ctypes
12
- import os
13
- import sys
14
-
15
- _HERE = os.path.dirname(os.path.abspath(__file__))
16
- _ENV = "GMAXFLOW_LIB"
17
-
18
-
19
- def _library_path() -> str:
20
- """$GMAXFLOW_LIB if set, else the library inside the installed package."""
21
- override = os.environ.get(_ENV)
22
- if override:
23
- return override
24
- name = {"win32": "gmaxflow_core.dll", "darwin": "gmaxflow_core.dylib"}.get(
25
- sys.platform, "gmaxflow_core.so"
26
- )
27
- return os.path.join(_HERE, "_native", name)
28
-
29
-
30
- def _load() -> ctypes.CDLL:
31
- path = _library_path()
32
- if not os.path.exists(path):
33
- raise ImportError(
34
- "the gmaxflow native solver was not found (%s). Install a wheel "
35
- "(`pip install generalized-maxflow`), or build from a checkout with "
36
- "`pip install .`; a library built by hand with CMake can be named in "
37
- "$%s." % (path, _ENV)
38
- )
39
- return ctypes.CDLL(path)
40
-
41
-
42
- _lib = _load()
43
-
44
- _lib.gmf_solve_json_n.restype = ctypes.c_void_p
45
- _lib.gmf_solve_json_n.argtypes = [
46
- ctypes.c_char_p,
47
- ctypes.c_size_t,
48
- ctypes.POINTER(ctypes.c_size_t),
49
- ]
50
- _lib.gmf_free.restype = None
51
- _lib.gmf_free.argtypes = [ctypes.c_void_p]
52
- _lib.gmf_version.restype = ctypes.c_char_p
53
- _lib.gmf_version.argtypes = []
54
-
55
-
56
- def solve_json(request: str) -> str:
57
- """Solve the JSON request and return the JSON answer."""
58
- data = request.encode("utf-8")
59
- size = ctypes.c_size_t(0)
60
- answer = _lib.gmf_solve_json_n(data, len(data), ctypes.byref(size))
61
- if not answer:
62
- raise MemoryError("the solver ran out of memory")
63
- try:
64
- return ctypes.string_at(answer, size.value).decode("utf-8")
65
- finally:
66
- _lib.gmf_free(answer)
67
-
68
-
69
- def version() -> str:
70
- return _lib.gmf_version().decode("ascii")
71
-
72
-
73
- def library_path() -> str:
74
- """Where the loaded native library lives, for diagnostics."""
75
- return _library_path()