U-Nesting
A high-performance 2D/3D spatial optimization engine for nesting and bin packing problems.
Features
- 2D Nesting: Optimal placement of irregular polygons on sheets
- 3D Bin Packing: Efficient box placement in containers
- Multiple Algorithms: BLF, NFP-guided, Genetic Algorithm, BRKGA, Simulated Annealing
- High Performance: Written in Rust with Python bindings
- Type Hints: Full type annotation support
Installation
pip install u-nesting
Quick Start
2D Nesting
import u_nesting
# Define polygons to nest
geometries = [
{
"id": "part1",
"polygon": [[0, 0], [100, 0], [100, 50], [0, 50]],
"quantity": 5,
"rotations": [0, 90, 180, 270]
},
{
"id": "triangle",
"polygon": [[0, 0], [80, 0], [40, 60]],
"quantity": 3
}
]
# Define sheet boundary
boundary = {"width": 500, "height": 300}
# Configure solver
config = {
"strategy": "nfp", # Options: blf, nfp, ga, brkga, sa, gdrr, alns
"spacing": 2.0, # Gap between parts
"time_limit_ms": 30000 # 30 second timeout
}
# Solve
result = u_nesting.solve_2d(geometries, boundary, config)
print(f"Utilization: {result['utilization']:.1%}")
print(f"Placed: {len(result['placements'])} items")
for p in result['placements']:
print(f" {p['geometry_id']}[{p['instance']}]: ({p['position'][0]:.1f}, {p['position'][1]:.1f})")
3D Bin Packing
import u_nesting
# Define boxes to pack
geometries = [
{
"id": "small",
"dimensions": [20, 20, 20],
"quantity": 10
},
{
"id": "large",
"dimensions": [40, 30, 25],
"quantity": 5,
"mass": 2.5 # Optional weight
}
]
# Define container
boundary = {
"dimensions": [200, 150, 100],
"max_mass": 50.0, # Optional mass limit
"gravity": True, # Stack from bottom
"stability": True # Require stable placement
}
# Configure solver
config = {
"strategy": "ep", # Extreme Point heuristic
"time_limit_ms": 10000
}
# Solve
result = u_nesting.solve_3d(geometries, boundary, config)
print(f"Utilization: {result['utilization']:.1%}")
print(f"Containers used: {result['boundaries_used']}")
API Reference
solve_2d(geometries, boundary, config=None) -> dict
Solve a 2D nesting problem.
Parameters:
Nothing a request asks for is raised as an exception: every refusal comes back in the result dict, with
successFalse, a stablecodeand the values behind it indetails-- the same codes and paths the C and WebAssembly bindings give. Branch oncode, not on theerrortext.
- Keys are read strictly: an unrecognized key in
geometries,boundaryorconfig, or a value of the wrong type -- a count given as a fraction (2.5) included -- ismalformed_inputwithdetailsparameterthe path of the field (config.stratgy,geometries[0].quantity). A typo can never silently fall back to a default.- A number that is not finite (
float("nan"),math.inf) isvalue_not_finite:parameteris the path of the value (config.spacing), or of the list it is in with its position asindex(geometries[0].polygon[2],index1 for the y coordinate), andidnames the geometry. A value JSON cannot hold (a set, a non-string key) ismalformed_input.- A value outside its range (a negative one included) is
parameter_out_of_range: a geometry'squantitybelow 1 hasparametergeometries[i].quantityand the geometry'sid; aconfigsetting (population_sizebelow 2,seedbelow 0, ...) hasparameterconfig.population_size; a boundary side, dimension ormax_massof 0 or below names it (boundary.width,boundary.dimensions[i],boundary.max_mass, withexclusive_min0).- An empty
geometrieslist isempty_input(parametergeometries); a strategy the dimension does not offer isinvalid_option(parameterconfig.strategy); a boundary given as both a rectangle and a polygon, or half of a rectangle, isinvalid_boundary.
geometries: List of geometry definitionsid(str): Unique identifierpolygon(list): Vertices as [[x, y], ...]quantity(int): Number of copies (default: 1)rotations(list): Allowed rotation angles in degrees — at least one; omit it for a fixed orientation (an empty list is refused)allow_flip(bool): Allow horizontal flipholes(list): Interior holes as list of polygons
boundary: Sheet definitionwidth,height(float): Rectangle dimensions, ORpolygon(list): Custom boundary shape
config: Solver configuration (optional)strategy(str): "blf", "nfp", "ga", "brkga", "sa", "gdrr", "alns"spacing(float): Gap between geometriesmargin(float): Gap from boundarytime_limit_ms(int): Timeout in milliseconds, at least 0 (0 = no limit; default 30000)target_utilization(float):ga,brkga,sastop once every part is placed at this utilization or more, in [0, 1]population_size(int): GA/BRKGA population, at least 2, run as given. Omitted, each search uses the size it is tuned for: 30 in 2Dmax_generations(int): GA/BRKGA generation budget, at least 0, run as given. Omitted, 50 in 2Dmax_iterations(int): SA/GDRR/ALNS iteration budget, at least 1; a seeded run that ends on it rather than on the time limit is reproduced exactly- A setting only some strategies read (
target_utilization,population_size,max_generations,max_iterations,crossover_rate,mutation_rate,seed) is refused asinvalid_optionunder a strategy that does not read it, not ignored crossover_rate/mutation_rate(float): GA crossover and mutation probabilities, in [0, 1] (default 0.85 / 0.05)seed(int): RNG seed ofga,brkga,sa,gdrr,alnsandhybridexact. The same problem with the same seed returns the same layout when the run ends on its own budget rather than on the clock (withtime_limit_ms0 a search runs to its own budget,max_generations/max_iterations)multi_sheet(bool): Distribute overflow across multiple sheets (default:False). WhenTrue, parts that do not fit on one sheet spill onto extra sheets instead of becoming unplaced;boundaries_usedreports the sheet count and each placement'sboundary_indexselects its sheet with sheet-local coordinates.
Returns: Dictionary with:
success(bool): Whether solve succeededplacements(list): Placement results (instance-level)utilization(float): Placed area over the area of the sheets taken (boundaries_used× the boundary's area), in every modeboundaries_used(int): Number of sheets used (>1 only whenmulti_sheet=True)total_requested(int): Σ of every geometry's quantity (instance-level total). Unplaced instance count =total_requested - len(placements)unplaced(list): Deduplicated IDs of items that couldn't be placed (not per-instance, solen(unplaced)under-reports the failed-instance count)unplaced_reasons(list): Why each entry ofunplacedis unplaced, in the same order:{"geometry_id": ..., "reason": "exceeds_boundary" | "no_room"}--exceeds_boundary: no allowed rotation of the part fits the sheet less the margin, so more sheets will not help;no_room: it fits, the layout was fullunplaced_count(int): Instance-level count of unplaced instancesall_placed(bool): Whether every requested instance was placed -- prefer it tosuccess, which only says the solve was not refusedused_bounding_box(list orNone):[width, height]of the placed parts' footprint;Nonewhere there is none (multi-sheet, nothing placed, 3D, a refusal) -- never[0, 0]used_utilization(float orNone): Part area overused_bounding_box;Noneexactly where it isstop_reason(str): Why the run stopped —completed(the method ran to its own end),optimal(an exact method proved it),target_reached(every part placed attarget_utilizationor more),iteration_limit,no_improvement(the search stalled),time_limit(time_limit_msran out; the layout is the best found by then) orcancelled(reachable only through the C ABI's progress callback -- a Python call takes no cancel argument, so bound a run withtime_limit_ms).Noneon a refusalcomputation_time_ms(int): Solve timeerror(str | None): Readable text when the request was refusedcode(str | None): Stable reason for that refusal (invalid_geometry,duplicate_id,parameter_out_of_range, ...)details(dict | None): The values behindcode(id,first,index,parameter,got, ...). A range gives each bounded side asmin/maxwhen the bound itself is accepted, orexclusive_min/exclusive_maxwhen it is not
solve_3d(geometries, boundary, config=None) -> dict
Solve a 3D bin packing problem.
Parameters:
geometries: List of box definitionsid(str): Unique identifierdimensions(list): [width, depth, height]quantity(int): Number of copiesmass(float): Weight, at least 0 (optional)orientation(str):"any","upright"or"fixed"(optional)
boundary: Container definitiondimensions(list): [width, depth, height], each above 0max_mass(float): Weight limit, above 0 (optional)gravity(bool): Enable gravity constraintstability(bool): Enable stability constraint
config: Same as solve_2d butmulti_sheet, which is refused (invalid_option,config.multi_sheet: one container, no sheets), and:strategy: "blf", "ep", "ga", "brkga", "sa"population_size/max_generationsomitted: 100 / 500 forga, 50 / 100 forbrkga
Returns: Same structure as solve_2d
available_strategies() -> dict
The strategies each dimension offers and the settings each reads:
{"2d": [{"name": "blf", "reads": ["spacing", ...]}, ...], "3d": [...]}. A setting the
chosen strategy does not read is refused (invalid_option), not ignored; this is the
table that refusal is made from, so a caller can offer only the settings that change
the run:
import u_nesting
catalog = u_nesting.available_strategies()
reads = {s["name"]: set(s["reads"]) for s in catalog["2d"]}
assert "target_utilization" in reads["ga"]
assert "target_utilization" not in reads["nfp"]
codes() -> dict
Every refusal code the functions answer with (with the details fields that can come
with it) and every violation code the checkers report:
{"refusals": [{"code", "fields"}], "violations": [{"code", "fields", "checkers"}]}. It is
read off the engine's own refusal and violation types, so a caller that translates codes
can check its list against the package's:
import u_nesting
known = {r["code"] for r in u_nesting.codes()["refusals"]}
assert "parameter_out_of_range" in known
Strategy Selection Guide
| Strategy | Speed | Quality | Best For |
|---|---|---|---|
blf |
Fast | Good | Large instances, quick results |
nfp |
Medium | Better | 2D with complex shapes |
ep |
Fast | Good | 3D bin packing |
ga |
Slow | Best | Small instances, max quality |
brkga |
Slow | Best | Complex constraints |
sa |
Medium | Better | Balanced speed/quality |
gdrr |
Medium | Better | 2D, ruin-and-recreate on dense layouts |
alns |
Medium | Better | 2D, adaptive neighborhood search |
Requirements
- Python 3.9+
- No additional dependencies
License
MIT License - see LICENSE for details.
Links
Metadata
Release files for u-nesting 0.29.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
| File | Actions Reset | |||
|---|---|---|---|---|
| u_nesting-0.29.0-cp39-abi3-win_amd64.whl | CPython 3.9 | abi3 | Windows x86-64 | Details for u_nesting-0.29.0-cp39-abi3-win_amd64.whl |
| u_nesting-0.29.0-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl | CPython 3.9 | abi3 | Linux glibc 2.17+ x86-64 | Details for u_nesting-0.29.0-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl |
| u_nesting-0.29.0-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl | CPython 3.9 | abi3 | Linux glibc 2.17+ ARM64 | Details for u_nesting-0.29.0-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl |
| u_nesting-0.29.0-cp39-abi3-macosx_11_0_arm64.whl | CPython 3.9 | abi3 | macOS 11.0+ ARM64 | Details for u_nesting-0.29.0-cp39-abi3-macosx_11_0_arm64.whl |
| u_nesting-0.29.0-cp39-abi3-macosx_10_12_x86_64.whl | CPython 3.9 | abi3 | macOS 10.12+ x86-64 | Details for u_nesting-0.29.0-cp39-abi3-macosx_10_12_x86_64.whl |
Total release size: 4.5 MB
Release files / u_nesting-0.29.0-cp39-abi3-win_amd64.whl
| Download URL | u_nesting-0.29.0-cp39-abi3-win_amd64.whl |
|---|---|
| Size | 901.7 kB |
| Tags | CPython 3.9 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
e55cadd1548ed8a79742e949d75299bb2fa364ba4d1202a8b89ec93e8b260c02
|
|
BLAKE2b-256 checksum How to use checksums |
eba3f2b984f1fa8d605d92b3cdbe6a21af79035fa02b4c0529342b0668fd554a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.
Transparency logRelease files / u_nesting-0.29.0-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
| Download URL | u_nesting-0.29.0-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl |
|---|---|
| Size | 955.9 kB |
| Tags | CPython 3.9 Linux glibc 2.17+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
047532d261ce8423c8209d852c14767c1a97e3e367d9fb7aef1dd8ac81f1fecb
|
|
BLAKE2b-256 checksum How to use checksums |
db46616e08a838e257714b9c4bd589fff8450d947e266b8da8dff837728ff8d8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.
Transparency logRelease files / u_nesting-0.29.0-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
| Download URL | u_nesting-0.29.0-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl |
|---|---|
| Size | 891.3 kB |
| Tags | CPython 3.9 Linux glibc 2.17+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
0ab5e90b6c8d20f103a399d933995e56319528d4da5ee3e7476dd7895c5c0362
|
|
BLAKE2b-256 checksum How to use checksums |
09de8bc17cd211b2d2c18d85ebea5816b4fd0449b88af5351d6a601e6e7194c8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.
Transparency logRelease files / u_nesting-0.29.0-cp39-abi3-macosx_11_0_arm64.whl
| Download URL | u_nesting-0.29.0-cp39-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 864.2 kB |
| Tags | CPython 3.9 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
fcc4b034c0697c51235293dabae136ee02d274a363adfa6ebd1271986a71c789
|
|
BLAKE2b-256 checksum How to use checksums |
1502ff23f3f2ea70a1e0f00897d4d4a03273781c587deb9222af84f7c246e14a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.
Transparency logRelease files / u_nesting-0.29.0-cp39-abi3-macosx_10_12_x86_64.whl
| Download URL | u_nesting-0.29.0-cp39-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 931.1 kB |
| Tags | CPython 3.9 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
86f78dfa6a43050cdb5a1acc6c02ef893aded61271b67a515b0431d54c04a605
|
|
BLAKE2b-256 checksum How to use checksums |
86a91b84cdbadfdf07a28a1b8e6a7821fbdd7482d5834548c5ddaef1e0894414
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.
Transparency logSecurity for u-nesting 0.29.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 5 files in this release have been uploaded with provenance metadata.
Attestation for u_nesting-0.29.0-cp39-abi3-win_amd64.whl
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.