pirilib 0.1.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.
- pirilib-0.1.0/.gitignore +25 -0
- pirilib-0.1.0/CHANGELOG.md +151 -0
- pirilib-0.1.0/LICENSE +202 -0
- pirilib-0.1.0/NOTICE +4 -0
- pirilib-0.1.0/PKG-INFO +121 -0
- pirilib-0.1.0/README.md +80 -0
- pirilib-0.1.0/docs/guide.md +604 -0
- pirilib-0.1.0/docs/objective.md +577 -0
- pirilib-0.1.0/docs/stability.md +104 -0
- pirilib-0.1.0/examples/README.md +16 -0
- pirilib-0.1.0/examples/linehaul_mini/README.md +23 -0
- pirilib-0.1.0/examples/linehaul_mini/centers.csv +7 -0
- pirilib-0.1.0/examples/linehaul_mini/demand.csv +19 -0
- pirilib-0.1.0/examples/linehaul_mini/problem.yaml +65 -0
- pirilib-0.1.0/examples/objectives/README.md +39 -0
- pirilib-0.1.0/examples/objectives/distance_aware.yaml +35 -0
- pirilib-0.1.0/examples/objectives/every_load.yaml +52 -0
- pirilib-0.1.0/examples/objectives/hard_min_fill.yaml +52 -0
- pirilib-0.1.0/examples/objectives/worked_cost.yaml +40 -0
- pirilib-0.1.0/pyproject.toml +135 -0
- pirilib-0.1.0/schemas/linehaul-0.2.schema.json +932 -0
- pirilib-0.1.0/src/pirilib/__init__.py +38 -0
- pirilib-0.1.0/src/pirilib/_version.py +1 -0
- pirilib-0.1.0/src/pirilib/bench/__init__.py +33 -0
- pirilib-0.1.0/src/pirilib/bench/families.py +323 -0
- pirilib-0.1.0/src/pirilib/bench/results.py +321 -0
- pirilib-0.1.0/src/pirilib/bench/runner.py +180 -0
- pirilib-0.1.0/src/pirilib/cli.py +528 -0
- pirilib-0.1.0/src/pirilib/constraints.py +143 -0
- pirilib-0.1.0/src/pirilib/errors.py +27 -0
- pirilib-0.1.0/src/pirilib/evaluation.py +462 -0
- pirilib-0.1.0/src/pirilib/forecast/__init__.py +74 -0
- pirilib-0.1.0/src/pirilib/forecast/bridge.py +112 -0
- pirilib-0.1.0/src/pirilib/forecast/evaluate.py +227 -0
- pirilib-0.1.0/src/pirilib/forecast/history.py +132 -0
- pirilib-0.1.0/src/pirilib/forecast/models.py +294 -0
- pirilib-0.1.0/src/pirilib/forecast/prepare.py +214 -0
- pirilib-0.1.0/src/pirilib/forecast/tune.py +115 -0
- pirilib-0.1.0/src/pirilib/forecast/waves.py +480 -0
- pirilib-0.1.0/src/pirilib/geo.py +31 -0
- pirilib-0.1.0/src/pirilib/objective.py +297 -0
- pirilib-0.1.0/src/pirilib/plan.py +286 -0
- pirilib-0.1.0/src/pirilib/planio.py +368 -0
- pirilib-0.1.0/src/pirilib/py.typed +0 -0
- pirilib-0.1.0/src/pirilib/solvers/__init__.py +41 -0
- pirilib-0.1.0/src/pirilib/solvers/_colony.py +1019 -0
- pirilib-0.1.0/src/pirilib/solvers/_routing.py +124 -0
- pirilib-0.1.0/src/pirilib/solvers/_sequential.py +142 -0
- pirilib-0.1.0/src/pirilib/solvers/_timing.py +209 -0
- pirilib-0.1.0/src/pirilib/solvers/aco.py +636 -0
- pirilib-0.1.0/src/pirilib/solvers/adapters/__init__.py +16 -0
- pirilib-0.1.0/src/pirilib/solvers/adapters/base.py +454 -0
- pirilib-0.1.0/src/pirilib/solvers/adapters/ortools_solver.py +139 -0
- pirilib-0.1.0/src/pirilib/solvers/adapters/pyvrp_solver.py +97 -0
- pirilib-0.1.0/src/pirilib/solvers/base.py +65 -0
- pirilib-0.1.0/src/pirilib/solvers/decompose.py +446 -0
- pirilib-0.1.0/src/pirilib/solvers/direct.py +202 -0
- pirilib-0.1.0/src/pirilib/solvers/exact.py +551 -0
- pirilib-0.1.0/src/pirilib/solvers/ledger.py +147 -0
- pirilib-0.1.0/src/pirilib/solvers/local_search.py +565 -0
- pirilib-0.1.0/src/pirilib/spec/__init__.py +57 -0
- pirilib-0.1.0/src/pirilib/spec/_format.py +95 -0
- pirilib-0.1.0/src/pirilib/spec/instance.py +223 -0
- pirilib-0.1.0/src/pirilib/spec/loader.py +58 -0
- pirilib-0.1.0/src/pirilib/spec/models.py +697 -0
- pirilib-0.1.0/src/pirilib/spec/schema.py +59 -0
- pirilib-0.1.0/src/pirilib/spec/tables.py +324 -0
- pirilib-0.1.0/src/pirilib/synthetic.py +324 -0
- pirilib-0.1.0/src/pirilib/tuning/__init__.py +28 -0
- pirilib-0.1.0/src/pirilib/tuning/bee_colony.py +203 -0
- pirilib-0.1.0/src/pirilib/tuning/space.py +132 -0
- pirilib-0.1.0/src/pirilib/tuning/tune.py +199 -0
- pirilib-0.1.0/src/pirilib/validate.py +369 -0
- pirilib-0.1.0/tests/conftest.py +296 -0
- pirilib-0.1.0/tests/fuzz/test_fuzz_inputs.py +464 -0
- pirilib-0.1.0/tests/model/test_ledger_model.py +274 -0
- pirilib-0.1.0/tests/performance/test_solver_time.py +199 -0
- pirilib-0.1.0/tests/spec/test_instance.py +320 -0
- pirilib-0.1.0/tests/spec/test_loader.py +430 -0
- pirilib-0.1.0/tests/spec/test_models.py +676 -0
- pirilib-0.1.0/tests/spec/test_objective_spec.py +401 -0
- pirilib-0.1.0/tests/spec/test_schema.py +239 -0
- pirilib-0.1.0/tests/test_aco.py +644 -0
- pirilib-0.1.0/tests/test_adapters.py +370 -0
- pirilib-0.1.0/tests/test_bench.py +356 -0
- pirilib-0.1.0/tests/test_cli.py +394 -0
- pirilib-0.1.0/tests/test_conftest.py +470 -0
- pirilib-0.1.0/tests/test_direct.py +551 -0
- pirilib-0.1.0/tests/test_docs_examples.py +382 -0
- pirilib-0.1.0/tests/test_evaluation.py +941 -0
- pirilib-0.1.0/tests/test_exact.py +293 -0
- pirilib-0.1.0/tests/test_forecast.py +462 -0
- pirilib-0.1.0/tests/test_geo.py +291 -0
- pirilib-0.1.0/tests/test_local_search.py +464 -0
- pirilib-0.1.0/tests/test_objective.py +311 -0
- pirilib-0.1.0/tests/test_package.py +133 -0
- pirilib-0.1.0/tests/test_plan.py +639 -0
- pirilib-0.1.0/tests/test_planio.py +223 -0
- pirilib-0.1.0/tests/test_schedule.py +395 -0
- pirilib-0.1.0/tests/test_synthetic.py +236 -0
- pirilib-0.1.0/tests/test_tuning.py +322 -0
- pirilib-0.1.0/tests/test_validate.py +236 -0
- pirilib-0.1.0/tests/test_waves.py +373 -0
pirilib-0.1.0/.gitignore
ADDED
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
__pycache__/
|
|
2
|
+
*.py[codz]
|
|
3
|
+
|
|
4
|
+
build/
|
|
5
|
+
dist/
|
|
6
|
+
site/
|
|
7
|
+
*.egg-info/
|
|
8
|
+
|
|
9
|
+
.venv/
|
|
10
|
+
venv/
|
|
11
|
+
|
|
12
|
+
.pytest_cache/
|
|
13
|
+
.hypothesis/
|
|
14
|
+
.mypy_cache/
|
|
15
|
+
.ruff_cache/
|
|
16
|
+
.coverage
|
|
17
|
+
htmlcov/
|
|
18
|
+
|
|
19
|
+
.vscode/
|
|
20
|
+
.idea/
|
|
21
|
+
.DS_Store
|
|
22
|
+
Thumbs.db
|
|
23
|
+
|
|
24
|
+
results/
|
|
25
|
+
data/private/
|
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project are documented in this file. The format
|
|
4
|
+
follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project
|
|
5
|
+
uses [Semantic Versioning](https://semver.org/).
|
|
6
|
+
|
|
7
|
+
[Unreleased]: https://github.com/mr-ozdemir/piriLIB/compare/v0.1.0...HEAD
|
|
8
|
+
[0.1.0]: https://github.com/mr-ozdemir/piriLIB/releases/tag/v0.1.0
|
|
9
|
+
|
|
10
|
+
## [Unreleased]
|
|
11
|
+
|
|
12
|
+
## [0.1.0] - 2026-11-16
|
|
13
|
+
|
|
14
|
+
### Added
|
|
15
|
+
|
|
16
|
+
- Project skeleton: src layout, hatchling build, Apache-2.0 license, typing
|
|
17
|
+
marker, test and lint tooling, continuous integration.
|
|
18
|
+
- Line-haul problem specification `pirilib/linehaul@0.1` (`pirilib.spec`):
|
|
19
|
+
calendar, centers, distance matrix (haversine or explicit arcs), vehicle types
|
|
20
|
+
with capacity per quantity dimension, owned vehicles and spot offers, demand,
|
|
21
|
+
and explicit business rules (minimum fill, stopovers, demand splitting).
|
|
22
|
+
- `pirilib.load_spec` reads YAML documents whose tables may come from CSV files
|
|
23
|
+
with configurable delimiter, encoding, decimal separator, date format and
|
|
24
|
+
column names. Every problem is reported at once, with file and line for CSV
|
|
25
|
+
rows.
|
|
26
|
+
- Consistency checks for references, duplicate ids, dimensions, the calendar,
|
|
27
|
+
distance coverage and whether every demand has an allowed vehicle.
|
|
28
|
+
- `LineHaulSpec.compile()` returns the problem as read-only numpy arrays.
|
|
29
|
+
- JSON Schema of problem documents in `schemas/linehaul-0.1.schema.json`.
|
|
30
|
+
- Synthetic example problem in `examples/linehaul_mini` (CC0-1.0).
|
|
31
|
+
- Plans (`pirilib.Plan`, `Dispatch`, `Load`): one-way multi-stop dispatches of
|
|
32
|
+
owned or spot vehicles with loads per demand, in array form.
|
|
33
|
+
- `pirilib.evaluate`: the single, numpy-vectorized computation of plan cost,
|
|
34
|
+
loads, fill and the violation amount of every built-in constraint
|
|
35
|
+
(`pirilib.constraints.CATALOG`), plus constraints of your own.
|
|
36
|
+
- `pirilib.objective`: weighted terms (cost, distance, dispatches, unused
|
|
37
|
+
capacity, unserved demand, violations) that add up to an objective; any
|
|
38
|
+
function of an evaluation works too.
|
|
39
|
+
- `pirilib.check_plan`: an independent plain-Python checker that explains every
|
|
40
|
+
violation in words; property tests compare it with the evaluator.
|
|
41
|
+
- `pirilib.solve` and `ACOSolver`: ant colony optimization over (day, origin)
|
|
42
|
+
subproblems, vectorized with numpy across ants and subproblems, with a
|
|
43
|
+
MAX-MIN hypercube pheromone model. Objectives with a linear form are
|
|
44
|
+
optimized subproblem by subproblem; any other objective, or constraints of
|
|
45
|
+
your own, are optimized on whole plans. All built-in rules except minimum
|
|
46
|
+
fill and coverage hold by construction.
|
|
47
|
+
- Local search on every subproblem's best routes: change vehicle, merge,
|
|
48
|
+
relocate, rebalance loads for minimum fill, serve leftover demand, and drop
|
|
49
|
+
routes that cost more than the demand they carry.
|
|
50
|
+
- `pirilib.solvers.exact.ExactSolver`: optimal solutions of small subproblems
|
|
51
|
+
by mixed-integer programming (extra `pirilib[exact]`, scipy/HiGHS), used as a
|
|
52
|
+
benchmark oracle and, with `ACOConfig(exact_nodes=...)`, inside the colony.
|
|
53
|
+
- `pirilib.tuning`: an artificial bee colony tuner (rank-based onlookers,
|
|
54
|
+
strict acceptance, modification rate, evaluation budget), random search as
|
|
55
|
+
the baseline, search spaces over the unit cube, and `tune()` for ACO settings
|
|
56
|
+
on training instances, with fixed seeds and a minimum-improvement guard.
|
|
57
|
+
- `pirilib` command line: `validate`, `solve`, `check`, `tune`, `generate`
|
|
58
|
+
and `schema`.
|
|
59
|
+
- Plan files (`pirilib.planio`): one row per load, with names instead of
|
|
60
|
+
indices, as CSV (Turkish spreadsheet format supported) or Excel (extra
|
|
61
|
+
`pirilib[excel]`), and read back for checking.
|
|
62
|
+
- `pirilib.synthetic`: synthetic problems with a gravity demand model.
|
|
63
|
+
- User guide in `docs/guide.md`; release workflow with trusted publishing.
|
|
64
|
+
- `pirilib.forecast`: daily demand per line from a history CSV; cleaning
|
|
65
|
+
without look-ahead, calendar and lag features, seasonal baselines,
|
|
66
|
+
`Regression` adapter for scikit-learn-style models, `lightgbm_tweedie` (extra
|
|
67
|
+
`pirilib[forecast]`), walk-forward `backtest`/`compare`, tuning with the bee
|
|
68
|
+
colony, and `planning_document` with quantile buffers to plan a forecast.
|
|
69
|
+
- `pirilib backtest` and `pirilib forecast` commands; synthetic histories in
|
|
70
|
+
`pirilib.synthetic.history`.
|
|
71
|
+
- Schema `pirilib/linehaul@0.2` (0.1 files still load): vehicle speeds,
|
|
72
|
+
hourly costs, demand ready and due times, a lateness penalty, deferral of
|
|
73
|
+
demand by days, handling minutes, daily handling capacity and vehicle
|
|
74
|
+
limits per center. Plans carry start times; the evaluator and the checker
|
|
75
|
+
compute the timeline, hourly costs, lateness (`service_cost`, part of
|
|
76
|
+
`total_cost`) and four new constraints (`ready`, `deferral`, `handling`,
|
|
77
|
+
`vehicle_limit`). Plan files have a `start` column.
|
|
78
|
+
- `BeeColony` starts from a Latin hypercube and, unless `sources` is set,
|
|
79
|
+
sizes the colony by the budget, which helps small tuning budgets.
|
|
80
|
+
- Local search is about ten times faster (plans and scores unchanged): cheap
|
|
81
|
+
pre-checks and remembered rejections of move candidates.
|
|
82
|
+
- `pirilib.forecast.Backtester` keeps fold settings for repeated backtests and
|
|
83
|
+
comparisons.
|
|
84
|
+
- Time waves in `pirilib.forecast`: `WaveSplitter` learns wave shares per line
|
|
85
|
+
and weekday from a wave-level history (`load_wave_history`) without
|
|
86
|
+
look-ahead, `planning_document(..., waves=...)` makes demand rows ready at
|
|
87
|
+
the wave times, and `pirilib forecast --waves` splits from the command line.
|
|
88
|
+
- Documentation site (MkDocs, Material theme) with the user guide and an API
|
|
89
|
+
reference generated from the docstrings; `docs` dependency group, and CI
|
|
90
|
+
builds it with `mkdocs build --strict`.
|
|
91
|
+
- `pirilib.bench` and `pirilib bench`: reproducible synthetic instance
|
|
92
|
+
families, a benchmark runner with CSV results and per-solver summaries, the
|
|
93
|
+
`DirectShipping` baseline, and optional `PyVRPSolver` and `ORToolsSolver`
|
|
94
|
+
adapters (extras `pirilib[pyvrp]`, `pirilib[ortools]`).
|
|
95
|
+
- The ant colony plans with times and center limits: on scheduled problems the
|
|
96
|
+
subproblems run in urgency order against a ledger of handling capacity and
|
|
97
|
+
vehicle slots per center and day, routes are timed (hourly costs and
|
|
98
|
+
lateness in the scores, also in local search), and demand that does not fit
|
|
99
|
+
waits for the next day within `max_deferral_days`. Objectives with a linear
|
|
100
|
+
form keep the fast path; whole-plan search keeps a ledger per ant.
|
|
101
|
+
- Documentation page "Building the objective" (`docs/objective.md`): the
|
|
102
|
+
`objective:` section field by field, the unit of every rule's penalty, a
|
|
103
|
+
worked total-cost example, advice on choosing weights (including coverage
|
|
104
|
+
against minimum fill), the same objective in Python, linear forms and speed,
|
|
105
|
+
tuning and benchmarks, and the real error messages. Example scenarios in
|
|
106
|
+
`examples/objectives` (every load goes, minimum fill as a hard rule,
|
|
107
|
+
distance-aware, the worked example), and `tests/test_docs_examples.py`,
|
|
108
|
+
which solves them, runs the page's Python blocks and checks its rule table
|
|
109
|
+
against `CATALOG` and its error messages against the code.
|
|
110
|
+
- `ExactSolver` plans problems with times, deferral, handling capacity and
|
|
111
|
+
vehicle limits when handling takes no time (`rules.handling.minutes_per_unit`
|
|
112
|
+
is 0).
|
|
113
|
+
- `read_plan` and `pirilib check` read .xlsx plans, as written by
|
|
114
|
+
`pirilib solve -o plan.xlsx`.
|
|
115
|
+
- Test levels (`unit`, `integration`, `system`) on every test, fuzz tests of
|
|
116
|
+
the plan and problem readers, a model-based test of the ledger, opt-in
|
|
117
|
+
performance tests (`pytest --performance`), branch coverage in CI and a
|
|
118
|
+
weekly quality workflow with mutation testing.
|
|
119
|
+
- `tune(validation=...)` and `pirilib tune --validation` score the best few
|
|
120
|
+
settings on validation instances and keep the base unless one beats it there.
|
|
121
|
+
- `pirilib.tuning.default_sources` is public.
|
|
122
|
+
- `docs/testing.md`: how the tests are organised and written, and how to run
|
|
123
|
+
the fuzz, model-based, performance and mutation tests.
|
|
124
|
+
- `SECURITY.md`, `CODE_OF_CONDUCT.md`, and issue and pull request templates.
|
|
125
|
+
|
|
126
|
+
### Changed
|
|
127
|
+
|
|
128
|
+
- The README is short: what pirilib does, installation, a quick start whose
|
|
129
|
+
output is tested, features and links. The development setup moved to
|
|
130
|
+
`CONTRIBUTING.md` and the roadmap to `docs/stability.md`.
|
|
131
|
+
- `pirilib forecast --network` warns when no `--quantile` buffer is given.
|
|
132
|
+
- The ant colony builds its solutions about 1.5 to 1.7 times faster, with the
|
|
133
|
+
same plans and scores to the last bit: per-option and per-node values are
|
|
134
|
+
laid out once per build, the weights of opening a route are kept and updated
|
|
135
|
+
only where a row loads, and sampling and each step use fewer numpy calls.
|
|
136
|
+
Large problems solve about a third faster in total.
|
|
137
|
+
- There is no default objective any more: `default_objective` and
|
|
138
|
+
`DEFAULT_PENALTY` are gone, and `objective` is a required argument of
|
|
139
|
+
`pirilib.solve`, `Solver.solve` (`ACOSolver`, `ExactSolver`, `DirectShipping`,
|
|
140
|
+
the routing adapters), `tuning.tune` and `bench.Benchmark`. Problem documents
|
|
141
|
+
define it in a new optional `objective:` section (`ObjectiveSpec`: `cost`,
|
|
142
|
+
`distance_km`, `dispatches`, `unused_capacity` and a penalty per rule, or
|
|
143
|
+
`other` for the rules not named; a rule without a penalty is an error), and
|
|
144
|
+
`LineHaulSpec.build_objective()` turns it into a `Sum`. The command line
|
|
145
|
+
`solve`, `tune` and `bench` read it from the documents, and their `--penalty`
|
|
146
|
+
option was removed. Generated documents and the example carry an explicit
|
|
147
|
+
`objective:` section.
|
|
148
|
+
- `BeeColony` without `sources` uses three food sources from 24 to 119
|
|
149
|
+
evaluations and four from 120 (before: four from 32), which did better on
|
|
150
|
+
test functions and on ACO tuning at the default budget of 40 settings. The
|
|
151
|
+
default budget stays 40.
|
pirilib-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
|
|
2
|
+
Apache License
|
|
3
|
+
Version 2.0, January 2004
|
|
4
|
+
http://www.apache.org/licenses/
|
|
5
|
+
|
|
6
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
7
|
+
|
|
8
|
+
1. Definitions.
|
|
9
|
+
|
|
10
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
11
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
12
|
+
|
|
13
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
14
|
+
the copyright owner that is granting the License.
|
|
15
|
+
|
|
16
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
17
|
+
other entities that control, are controlled by, or are under common
|
|
18
|
+
control with that entity. For the purposes of this definition,
|
|
19
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
20
|
+
direction or management of such entity, whether by contract or
|
|
21
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
22
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
23
|
+
|
|
24
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
25
|
+
exercising permissions granted by this License.
|
|
26
|
+
|
|
27
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
28
|
+
including but not limited to software source code, documentation
|
|
29
|
+
source, and configuration files.
|
|
30
|
+
|
|
31
|
+
"Object" form shall mean any form resulting from mechanical
|
|
32
|
+
transformation or translation of a Source form, including but
|
|
33
|
+
not limited to compiled object code, generated documentation,
|
|
34
|
+
and conversions to other media types.
|
|
35
|
+
|
|
36
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
37
|
+
Object form, made available under the License, as indicated by a
|
|
38
|
+
copyright notice that is included in or attached to the work
|
|
39
|
+
(an example is provided in the Appendix below).
|
|
40
|
+
|
|
41
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
42
|
+
form, that is based on (or derived from) the Work and for which the
|
|
43
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
44
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
45
|
+
of this License, Derivative Works shall not include works that remain
|
|
46
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
47
|
+
the Work and Derivative Works thereof.
|
|
48
|
+
|
|
49
|
+
"Contribution" shall mean any work of authorship, including
|
|
50
|
+
the original version of the Work and any modifications or additions
|
|
51
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
52
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
53
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
54
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
55
|
+
means any form of electronic, verbal, or written communication sent
|
|
56
|
+
to the Licensor or its representatives, including but not limited to
|
|
57
|
+
communication on electronic mailing lists, source code control systems,
|
|
58
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
59
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
60
|
+
excluding communication that is conspicuously marked or otherwise
|
|
61
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
62
|
+
|
|
63
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
64
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
65
|
+
subsequently incorporated within the Work.
|
|
66
|
+
|
|
67
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
68
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
69
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
70
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
71
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
72
|
+
Work and such Derivative Works in Source or Object form.
|
|
73
|
+
|
|
74
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
75
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
76
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
77
|
+
(except as stated in this section) patent license to make, have made,
|
|
78
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
79
|
+
where such license applies only to those patent claims licensable
|
|
80
|
+
by such Contributor that are necessarily infringed by their
|
|
81
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
82
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
83
|
+
institute patent litigation against any entity (including a
|
|
84
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
85
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
86
|
+
or contributory patent infringement, then any patent licenses
|
|
87
|
+
granted to You under this License for that Work shall terminate
|
|
88
|
+
as of the date such litigation is filed.
|
|
89
|
+
|
|
90
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
91
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
92
|
+
modifications, and in Source or Object form, provided that You
|
|
93
|
+
meet the following conditions:
|
|
94
|
+
|
|
95
|
+
(a) You must give any other recipients of the Work or
|
|
96
|
+
Derivative Works a copy of this License; and
|
|
97
|
+
|
|
98
|
+
(b) You must cause any modified files to carry prominent notices
|
|
99
|
+
stating that You changed the files; and
|
|
100
|
+
|
|
101
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
102
|
+
that You distribute, all copyright, patent, trademark, and
|
|
103
|
+
attribution notices from the Source form of the Work,
|
|
104
|
+
excluding those notices that do not pertain to any part of
|
|
105
|
+
the Derivative Works; and
|
|
106
|
+
|
|
107
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
108
|
+
distribution, then any Derivative Works that You distribute must
|
|
109
|
+
include a readable copy of the attribution notices contained
|
|
110
|
+
within such NOTICE file, excluding those notices that do not
|
|
111
|
+
pertain to any part of the Derivative Works, in at least one
|
|
112
|
+
of the following places: within a NOTICE text file distributed
|
|
113
|
+
as part of the Derivative Works; within the Source form or
|
|
114
|
+
documentation, if provided along with the Derivative Works; or,
|
|
115
|
+
within a display generated by the Derivative Works, if and
|
|
116
|
+
wherever such third-party notices normally appear. The contents
|
|
117
|
+
of the NOTICE file are for informational purposes only and
|
|
118
|
+
do not modify the License. You may add Your own attribution
|
|
119
|
+
notices within Derivative Works that You distribute, alongside
|
|
120
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
121
|
+
that such additional attribution notices cannot be construed
|
|
122
|
+
as modifying the License.
|
|
123
|
+
|
|
124
|
+
You may add Your own copyright statement to Your modifications and
|
|
125
|
+
may provide additional or different license terms and conditions
|
|
126
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
127
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
128
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
129
|
+
the conditions stated in this License.
|
|
130
|
+
|
|
131
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
132
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
133
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
134
|
+
this License, without any additional terms or conditions.
|
|
135
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
136
|
+
the terms of any separate license agreement you may have executed
|
|
137
|
+
with Licensor regarding such Contributions.
|
|
138
|
+
|
|
139
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
140
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
141
|
+
except as required for reasonable and customary use in describing the
|
|
142
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
143
|
+
|
|
144
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
145
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
146
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
147
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
148
|
+
implied, including, without limitation, any warranties or conditions
|
|
149
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
150
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
151
|
+
appropriateness of using or redistributing the Work and assume any
|
|
152
|
+
risks associated with Your exercise of permissions under this License.
|
|
153
|
+
|
|
154
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
155
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
156
|
+
unless required by applicable law (such as deliberate and grossly
|
|
157
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
158
|
+
liable to You for damages, including any direct, indirect, special,
|
|
159
|
+
incidental, or consequential damages of any character arising as a
|
|
160
|
+
result of this License or out of the use or inability to use the
|
|
161
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
162
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
163
|
+
other commercial damages or losses), even if such Contributor
|
|
164
|
+
has been advised of the possibility of such damages.
|
|
165
|
+
|
|
166
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
167
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
168
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
169
|
+
or other liability obligations and/or rights consistent with this
|
|
170
|
+
License. However, in accepting such obligations, You may act only
|
|
171
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
172
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
173
|
+
defend, and hold each Contributor harmless for any liability
|
|
174
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
175
|
+
of your accepting any such warranty or additional liability.
|
|
176
|
+
|
|
177
|
+
END OF TERMS AND CONDITIONS
|
|
178
|
+
|
|
179
|
+
APPENDIX: How to apply the Apache License to your work.
|
|
180
|
+
|
|
181
|
+
To apply the Apache License to your work, attach the following
|
|
182
|
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
|
183
|
+
replaced with your own identifying information. (Don't include
|
|
184
|
+
the brackets!) The text should be enclosed in the appropriate
|
|
185
|
+
comment syntax for the file format. We also recommend that a
|
|
186
|
+
file or class name and description of purpose be included on the
|
|
187
|
+
same "printed page" as the copyright notice for easier
|
|
188
|
+
identification within third-party archives.
|
|
189
|
+
|
|
190
|
+
Copyright [yyyy] [name of copyright owner]
|
|
191
|
+
|
|
192
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
193
|
+
you may not use this file except in compliance with the License.
|
|
194
|
+
You may obtain a copy of the License at
|
|
195
|
+
|
|
196
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
197
|
+
|
|
198
|
+
Unless required by applicable law or agreed to in writing, software
|
|
199
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
200
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
201
|
+
See the License for the specific language governing permissions and
|
|
202
|
+
limitations under the License.
|
pirilib-0.1.0/NOTICE
ADDED
pirilib-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: pirilib
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Fleet optimization with an ant colony solver, a bee colony tuner and your own objective and constraints, starting with line-haul planning.
|
|
5
|
+
Project-URL: Homepage, https://github.com/mr-ozdemir/piriLIB
|
|
6
|
+
Project-URL: Documentation, https://github.com/mr-ozdemir/piriLIB/blob/master/docs/guide.md
|
|
7
|
+
Project-URL: Changelog, https://github.com/mr-ozdemir/piriLIB/blob/master/CHANGELOG.md
|
|
8
|
+
Project-URL: Issues, https://github.com/mr-ozdemir/piriLIB/issues
|
|
9
|
+
Author-email: Muhammet Ozdemir <mr.ozdemir34@gmail.com>
|
|
10
|
+
License-Expression: Apache-2.0
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
License-File: NOTICE
|
|
13
|
+
Keywords: ant colony optimization,artificial bee colony,demand forecasting,fleet optimization,line-haul,logistics,metaheuristics,vehicle routing
|
|
14
|
+
Classifier: Development Status :: 3 - Alpha
|
|
15
|
+
Classifier: Intended Audience :: Developers
|
|
16
|
+
Classifier: Intended Audience :: Science/Research
|
|
17
|
+
Classifier: Operating System :: OS Independent
|
|
18
|
+
Classifier: Programming Language :: Python :: 3
|
|
19
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
23
|
+
Classifier: Topic :: Scientific/Engineering :: Mathematics
|
|
24
|
+
Classifier: Typing :: Typed
|
|
25
|
+
Requires-Python: >=3.12
|
|
26
|
+
Requires-Dist: numpy>=2.0
|
|
27
|
+
Requires-Dist: pydantic>=2.7
|
|
28
|
+
Requires-Dist: pyyaml>=6.0
|
|
29
|
+
Provides-Extra: exact
|
|
30
|
+
Requires-Dist: scipy>=1.14; extra == 'exact'
|
|
31
|
+
Provides-Extra: excel
|
|
32
|
+
Requires-Dist: openpyxl>=3.1; extra == 'excel'
|
|
33
|
+
Provides-Extra: forecast
|
|
34
|
+
Requires-Dist: lightgbm>=4.0; extra == 'forecast'
|
|
35
|
+
Requires-Dist: scikit-learn>=1.4; extra == 'forecast'
|
|
36
|
+
Provides-Extra: ortools
|
|
37
|
+
Requires-Dist: ortools>=9.15; extra == 'ortools'
|
|
38
|
+
Provides-Extra: pyvrp
|
|
39
|
+
Requires-Dist: pyvrp>=0.14; extra == 'pyvrp'
|
|
40
|
+
Description-Content-Type: text/markdown
|
|
41
|
+
|
|
42
|
+
# pirilib
|
|
43
|
+
|
|
44
|
+
Fleet optimization with an ant colony solver, a bee colony tuner and your own objective.
|
|
45
|
+
|
|
46
|
+
[](https://github.com/mr-ozdemir/piriLIB/actions/workflows/ci.yml)
|
|
47
|
+
[](https://pypi.org/project/pirilib/)
|
|
48
|
+
[](https://github.com/mr-ozdemir/piriLIB/blob/master/pyproject.toml)
|
|
49
|
+
[](https://github.com/mr-ozdemir/piriLIB/blob/master/LICENSE)
|
|
50
|
+
|
|
51
|
+
Describe the fleet, the demand and the rules in YAML, write what a good plan
|
|
52
|
+
means, and pirilib searches for the plan that serves the demand at the lowest
|
|
53
|
+
cost. One evaluator scores every plan the same way, whichever solver made it.
|
|
54
|
+
|
|
55
|
+
> **Alpha.** pirilib 0.1 is the first alpha; the API may change before 1.0.
|
|
56
|
+
> See [Public API and stability](https://github.com/mr-ozdemir/piriLIB/blob/master/docs/stability.md).
|
|
57
|
+
|
|
58
|
+
## Installation
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
pip install pirilib
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
pirilib needs Python 3.12+. Optional extras: `exact` (scipy), `excel`
|
|
65
|
+
(openpyxl), `forecast` (LightGBM, scikit-learn), `pyvrp` and `ortools`, for
|
|
66
|
+
example `pip install "pirilib[exact,excel]"`.
|
|
67
|
+
|
|
68
|
+
## Quick start
|
|
69
|
+
|
|
70
|
+
```pycon
|
|
71
|
+
>>> import pirilib
|
|
72
|
+
>>> spec = pirilib.load_spec("examples/linehaul_mini/problem.yaml")
|
|
73
|
+
>>> result = pirilib.solve(spec.compile(), spec.build_objective(), seed=1)
|
|
74
|
+
>>> result.evaluation
|
|
75
|
+
Evaluation(total_cost=178394.63, dispatches=18, total_km=2891.0, feasible)
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Or from the command line:
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
pirilib generate sample --centers 20 --days 3
|
|
82
|
+
pirilib solve sample/problem.yaml -o plan.csv
|
|
83
|
+
pirilib check sample/problem.yaml plan.csv
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
## Features
|
|
87
|
+
|
|
88
|
+
- **Line-haul planning** with owned and spot vehicles, multi-stop routes, split
|
|
89
|
+
loads, times and deferral, handling capacity and vehicle limits.
|
|
90
|
+
- **Ant colony solver** in numpy with local search, and an exact solver for
|
|
91
|
+
small problems.
|
|
92
|
+
- **Your objective**: cost, distance and a penalty for every rule, in YAML or
|
|
93
|
+
Python, with an independent plan checker.
|
|
94
|
+
- **Bee colony tuner** for the solver settings, validated on held-out problems.
|
|
95
|
+
- **Demand forecasting** per line, with backtests and a bridge from the
|
|
96
|
+
forecast to a planning problem.
|
|
97
|
+
- **Clear errors**: every problem in a document is reported at once, with file
|
|
98
|
+
and line for table rows.
|
|
99
|
+
|
|
100
|
+
## Documentation
|
|
101
|
+
|
|
102
|
+
- [User guide](https://github.com/mr-ozdemir/piriLIB/blob/master/docs/guide.md)
|
|
103
|
+
- [Building the objective](https://github.com/mr-ozdemir/piriLIB/blob/master/docs/objective.md)
|
|
104
|
+
- [Public API and stability](https://github.com/mr-ozdemir/piriLIB/blob/master/docs/stability.md)
|
|
105
|
+
- [Examples](https://github.com/mr-ozdemir/piriLIB/tree/master/examples)
|
|
106
|
+
|
|
107
|
+
## Contributing
|
|
108
|
+
|
|
109
|
+
See [CONTRIBUTING.md](https://github.com/mr-ozdemir/piriLIB/blob/master/CONTRIBUTING.md).
|
|
110
|
+
|
|
111
|
+
## License
|
|
112
|
+
|
|
113
|
+
Apache-2.0. Example data is synthetic; no third-party or competition data is
|
|
114
|
+
distributed.
|
|
115
|
+
|
|
116
|
+
## Türkçe
|
|
117
|
+
|
|
118
|
+
pirilib, filo optimizasyonu kütüphanesidir: problemi YAML ile tanımlarsınız,
|
|
119
|
+
ACO çözücü amaç fonksiyonunuza göre en iyi planı arar, ABC ayarlayıcı çözücü
|
|
120
|
+
ayarlarını bulur. CSV tabloları Türkçe biçimde (`;`, ondalık virgül, `gg.aa.yyyy`)
|
|
121
|
+
okunur ve yazılır, planlar Excel'e de yazılıp okunur.
|
pirilib-0.1.0/README.md
ADDED
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
# pirilib
|
|
2
|
+
|
|
3
|
+
Fleet optimization with an ant colony solver, a bee colony tuner and your own objective.
|
|
4
|
+
|
|
5
|
+
[](https://github.com/mr-ozdemir/piriLIB/actions/workflows/ci.yml)
|
|
6
|
+
[](https://pypi.org/project/pirilib/)
|
|
7
|
+
[](https://github.com/mr-ozdemir/piriLIB/blob/master/pyproject.toml)
|
|
8
|
+
[](https://github.com/mr-ozdemir/piriLIB/blob/master/LICENSE)
|
|
9
|
+
|
|
10
|
+
Describe the fleet, the demand and the rules in YAML, write what a good plan
|
|
11
|
+
means, and pirilib searches for the plan that serves the demand at the lowest
|
|
12
|
+
cost. One evaluator scores every plan the same way, whichever solver made it.
|
|
13
|
+
|
|
14
|
+
> **Alpha.** pirilib 0.1 is the first alpha; the API may change before 1.0.
|
|
15
|
+
> See [Public API and stability](https://github.com/mr-ozdemir/piriLIB/blob/master/docs/stability.md).
|
|
16
|
+
|
|
17
|
+
## Installation
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
pip install pirilib
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
pirilib needs Python 3.12+. Optional extras: `exact` (scipy), `excel`
|
|
24
|
+
(openpyxl), `forecast` (LightGBM, scikit-learn), `pyvrp` and `ortools`, for
|
|
25
|
+
example `pip install "pirilib[exact,excel]"`.
|
|
26
|
+
|
|
27
|
+
## Quick start
|
|
28
|
+
|
|
29
|
+
```pycon
|
|
30
|
+
>>> import pirilib
|
|
31
|
+
>>> spec = pirilib.load_spec("examples/linehaul_mini/problem.yaml")
|
|
32
|
+
>>> result = pirilib.solve(spec.compile(), spec.build_objective(), seed=1)
|
|
33
|
+
>>> result.evaluation
|
|
34
|
+
Evaluation(total_cost=178394.63, dispatches=18, total_km=2891.0, feasible)
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Or from the command line:
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
pirilib generate sample --centers 20 --days 3
|
|
41
|
+
pirilib solve sample/problem.yaml -o plan.csv
|
|
42
|
+
pirilib check sample/problem.yaml plan.csv
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
## Features
|
|
46
|
+
|
|
47
|
+
- **Line-haul planning** with owned and spot vehicles, multi-stop routes, split
|
|
48
|
+
loads, times and deferral, handling capacity and vehicle limits.
|
|
49
|
+
- **Ant colony solver** in numpy with local search, and an exact solver for
|
|
50
|
+
small problems.
|
|
51
|
+
- **Your objective**: cost, distance and a penalty for every rule, in YAML or
|
|
52
|
+
Python, with an independent plan checker.
|
|
53
|
+
- **Bee colony tuner** for the solver settings, validated on held-out problems.
|
|
54
|
+
- **Demand forecasting** per line, with backtests and a bridge from the
|
|
55
|
+
forecast to a planning problem.
|
|
56
|
+
- **Clear errors**: every problem in a document is reported at once, with file
|
|
57
|
+
and line for table rows.
|
|
58
|
+
|
|
59
|
+
## Documentation
|
|
60
|
+
|
|
61
|
+
- [User guide](https://github.com/mr-ozdemir/piriLIB/blob/master/docs/guide.md)
|
|
62
|
+
- [Building the objective](https://github.com/mr-ozdemir/piriLIB/blob/master/docs/objective.md)
|
|
63
|
+
- [Public API and stability](https://github.com/mr-ozdemir/piriLIB/blob/master/docs/stability.md)
|
|
64
|
+
- [Examples](https://github.com/mr-ozdemir/piriLIB/tree/master/examples)
|
|
65
|
+
|
|
66
|
+
## Contributing
|
|
67
|
+
|
|
68
|
+
See [CONTRIBUTING.md](https://github.com/mr-ozdemir/piriLIB/blob/master/CONTRIBUTING.md).
|
|
69
|
+
|
|
70
|
+
## License
|
|
71
|
+
|
|
72
|
+
Apache-2.0. Example data is synthetic; no third-party or competition data is
|
|
73
|
+
distributed.
|
|
74
|
+
|
|
75
|
+
## Türkçe
|
|
76
|
+
|
|
77
|
+
pirilib, filo optimizasyonu kütüphanesidir: problemi YAML ile tanımlarsınız,
|
|
78
|
+
ACO çözücü amaç fonksiyonunuza göre en iyi planı arar, ABC ayarlayıcı çözücü
|
|
79
|
+
ayarlarını bulur. CSV tabloları Türkçe biçimde (`;`, ondalık virgül, `gg.aa.yyyy`)
|
|
80
|
+
okunur ve yazılır, planlar Excel'e de yazılıp okunur.
|