0
# Geometry and Alignment
1

2
Geometry and alignment in pyparted provide precise control over partition positioning and alignment constraints. These classes are essential for ensuring partitions are properly positioned for optimal performance and compatibility.
3

4
## Capabilities
5

6
### Geometry Class
7

8
The Geometry class represents a contiguous region of sectors on a storage device.
9

10
```python { .api }
11
class Geometry:
12
    """
13
    Geometry represents a region on a device expressed as starting sector and length.
14
    Used throughout pyparted for defining partition boundaries and operations.
15
    """
16
    
17
    # Properties
18
    device: Device  # Associated device object
19
    start: int      # Starting sector number
20
    end: int        # Ending sector number (inclusive)
21
    length: int     # Length in sectors
22
```
23

24
### Geometry Creation
25

26
Constructor and creation methods for geometry objects.
27

28
```python { .api }
29
class Geometry:
30
    def __init__(device: Device, start: int = None, length: int = None, 
31
                 end: int = None) -> Geometry:
32
        """
33
        Create new geometry object.
34
        
35
        Args:
36
            device (Device): Device object
37
            start (int): Starting sector
38
            length (int): Length in sectors (alternative to end)
39
            end (int): Ending sector (alternative to length)
40
            
41
        Raises:
42
            GeometryException: If parameters are invalid
43
        """
44
    
45
    def duplicate() -> Geometry:
46
        """
47
        Create a copy of this geometry.
48
        
49
        Returns:
50
            Geometry: Duplicated geometry object
51
            
52
        Raises:
53
            CreateException: If duplication fails
54
        """
55
```
56

57
### Geometry Operations
58

59
Methods for geometry manipulation and calculations.
60

61
```python { .api }
62
class Geometry:
63
    def intersect(geometry: Geometry) -> Geometry:
64
        """
65
        Create geometry representing intersection with another geometry.
66
        
67
        Args:
68
            geometry (Geometry): Geometry to intersect with
69
            
70
        Returns:
71
            Geometry: Intersection geometry or None if no overlap
72
            
73
        Raises:
74
            CreateException: If intersection calculation fails
75
        """
76
    
77
    def overlapsWith(geometry: Geometry) -> bool:
78
        """
79
        Check if this geometry overlaps with another.
80
        
81
        Args:
82
            geometry (Geometry): Geometry to check against
83
            
84
        Returns:
85
            bool: True if geometries overlap
86
        """
87
    
88
    def contains(geometry: Geometry) -> bool:
89
        """
90
        Check if this geometry completely contains another.
91
        
92
        Args:
93
            geometry (Geometry): Geometry to check
94
            
95
        Returns:
96
            bool: True if this geometry contains the other
97
        """
98
    
99
    def containsSector(sector: int) -> bool:
100
        """
101
        Check if this geometry contains the specified sector.
102
        
103
        Args:
104
            sector (int): Sector number to check
105
            
106
        Returns:
107
            bool: True if sector is within this geometry
108
        """
109
    
110
    def equal(geometry: Geometry) -> bool:
111
        """
112
        Check if this geometry is equal to another.
113
        
114
        Args:
115
            geometry (Geometry): Geometry to compare
116
            
117
        Returns:
118
            bool: True if geometries are equal
119
        """
120
```
121

122
### Geometry Modification
123

124
Methods for modifying geometry parameters.
125

126
```python { .api }
127
class Geometry:
128
    def set(start: int, length: int) -> None:
129
        """
130
        Set geometry start and length.
131
        
132
        Args:
133
            start (int): New starting sector
134
            length (int): New length in sectors
135
            
136
        Raises:
137
            GeometryException: If parameters are invalid
138
        """
139
    
140
    def setStart(start: int) -> None:
141
        """
142
        Set geometry starting sector.
143
        
144
        Args:
145
            start (int): New starting sector
146
            
147
        Raises:
148
            GeometryException: If start is invalid
149
        """
150
    
151
    def setEnd(end: int) -> None:
152
        """
153
        Set geometry ending sector.
154
        
155
        Args:
156
            end (int): New ending sector
157
            
158
        Raises:
159
            GeometryException: If end is invalid
160
        """
161
```
162

163
### Geometry I/O Operations
164

165
Methods for reading and writing to geometry regions.
166

167
```python { .api }
168
class Geometry:
169
    def read(offset: int, count: int) -> bytes:
170
        """
171
        Read data from geometry region.
172
        
173
        Args:
174
            offset (int): Offset in sectors from geometry start
175
            count (int): Number of sectors to read
176
            
177
        Returns:
178
            bytes: Data read from geometry
179
            
180
        Raises:
181
            IOException: If read operation fails
182
        """
183
    
184
    def write(buffer: bytes, offset: int, count: int) -> None:
185
        """
186
        Write data to geometry region.
187
        
188
        Args:
189
            buffer (bytes): Data to write
190
            offset (int): Offset in sectors from geometry start
191
            count (int): Number of sectors to write
192
            
193
        Raises:
194
            IOException: If write operation fails
195
        """
196
    
197
    def sync() -> None:
198
        """
199
        Synchronize geometry region.
200
        
201
        Raises:
202
            IOException: If sync operation fails
203
        """
204
    
205
    def syncFast() -> None:
206
        """
207
        Fast synchronization of geometry region.
208
        
209
        Raises:
210
            IOException: If sync operation fails
211
        """
212
    
213
    def check(offset: int, granularity: int, count: int, 
214
              timer: object = None) -> bool:
215
        """
216
        Check geometry region for errors.
217
        
218
        Args:
219
            offset (int): Offset in sectors from geometry start
220
            granularity (int): Granularity for checking
221
            count (int): Number of sectors to check
222
            timer (object, optional): Timer object for progress
223
            
224
        Returns:
225
            bool: True if region is healthy
226
            
227
        Raises:
228
            IOException: If check operation fails
229
        """
230
    
231
    def map(dst_geometry: Geometry, sector: int) -> int:
232
        """
233
        Map sector from this geometry to destination geometry.
234
        
235
        Args:
236
            dst_geometry (Geometry): Destination geometry
237
            sector (int): Sector to map
238
            
239
        Returns:
240
            int: Mapped sector in destination geometry
241
            
242
        Raises:
243
            GeometryException: If mapping fails
244
        """
245
```
246

247
### Alignment Class
248

249
The Alignment class describes constraints on sector alignment.
250

251
```python { .api }
252
class Alignment:
253
    """
254
    Alignment describes constraints on how sectors and geometries are aligned.
255
    Used to ensure partitions start and end at optimal sector boundaries.
256
    """
257
    
258
    # Properties
259
    offset: int     # Alignment offset
260
    grainSize: int  # Alignment grain size (alignment multiple)
261
```
262

263
### Alignment Creation
264

265
Constructor for creating alignment objects.
266

267
```python { .api }
268
class Alignment:
269
    def __init__(offset: int, grainSize: int) -> Alignment:
270
        """
271
        Create new alignment object.
272
        
273
        Args:
274
            offset (int): Alignment offset
275
            grainSize (int): Alignment grain size
276
            
277
        Raises:
278
            AlignmentException: If parameters are invalid
279
        """
280
```
281

282
### Alignment Operations
283

284
Methods for alignment calculations and operations.
285

286
```python { .api }
287
class Alignment:
288
    def intersect(alignment: Alignment) -> Alignment:
289
        """
290
        Create alignment representing intersection with another alignment.
291
        
292
        Args:
293
            alignment (Alignment): Alignment to intersect with
294
            
295
        Returns:
296
            Alignment: Intersection alignment
297
            
298
        Raises:
299
            ArithmeticError: If intersection calculation fails
300
        """
301
    
302
    def alignUp(geometry: Geometry, sector: int) -> int:
303
        """
304
        Align sector upward to next aligned position.
305
        
306
        Args:
307
            geometry (Geometry): Geometry context for alignment
308
            sector (int): Sector to align
309
            
310
        Returns:
311
            int: Next aligned sector >= input sector
312
            
313
        Raises:
314
            ArithmeticError: If alignment calculation fails
315
        """
316
    
317
    def alignDown(geometry: Geometry, sector: int) -> int:
318
        """
319
        Align sector downward to previous aligned position.
320
        
321
        Args:
322
            geometry (Geometry): Geometry context for alignment
323
            sector (int): Sector to align
324
            
325
        Returns:
326
            int: Previous aligned sector <= input sector
327
            
328
        Raises:
329
            ArithmeticError: If alignment calculation fails
330
        """
331
    
332
    def alignNearest(geometry: Geometry, sector: int) -> int:
333
        """
334
        Align sector to nearest aligned position.
335
        
336
        Args:
337
            geometry (Geometry): Geometry context for alignment
338
            sector (int): Sector to align
339
            
340
        Returns:
341
            int: Nearest aligned sector
342
            
343
        Raises:
344
            ArithmeticError: If alignment calculation fails
345
        """
346
    
347
    def isAligned(geometry: Geometry, sector: int) -> bool:
348
        """
349
        Check if sector is properly aligned.
350
        
351
        Args:
352
            geometry (Geometry): Geometry context for alignment
353
            sector (int): Sector to check
354
            
355
        Returns:
356
            bool: True if sector is aligned
357
        """
358
```
359

360
## Usage Examples
361

362
### Basic Geometry Operations
363

364
```python
365
import parted
366

367
device = parted.getDevice('/dev/sda')
368

369
# Create geometry for first 1GB of device
370
sectors_per_gb = (1024**3) // device.sectorSize
371
geometry1 = parted.Geometry(device, start=0, length=sectors_per_gb)
372

373
# Create geometry for second 1GB
374
geometry2 = parted.Geometry(device, start=sectors_per_gb, length=sectors_per_gb)
375

376
print(f"Geometry 1: sectors {geometry1.start} to {geometry1.end}")
377
print(f"Geometry 2: sectors {geometry2.start} to {geometry2.end}")
378

379
# Check for overlap
380
if geometry1.overlapsWith(geometry2):
381
    print("Geometries overlap")
382
else:
383
    print("Geometries don't overlap")
384

385
# Check if geometry contains specific sector
386
if geometry1.containsSector(500000):
387
    print("Geometry 1 contains sector 500000")
388
```
389

390
### Geometry Intersection
391

392
```python
393
import parted
394

395
device = parted.getDevice('/dev/sda')
396

397
# Create overlapping geometries
398
geom1 = parted.Geometry(device, start=1000, length=2000)  # sectors 1000-2999
399
geom2 = parted.Geometry(device, start=2000, length=2000)  # sectors 2000-3999
400

401
# Find intersection
402
intersection = geom1.intersect(geom2)
403
if intersection:
404
    print(f"Intersection: sectors {intersection.start} to {intersection.end}")
405
    print(f"Intersection length: {intersection.length} sectors")
406
else:
407
    print("No intersection")
408
```
409

410
### Working with Alignment
411

412
```python
413
import parted
414

415
device = parted.getDevice('/dev/sda')
416

417
# Get device optimal alignment
418
optimal_alignment = device.getOptimumAlignment()
419
print(f"Optimal alignment - offset: {optimal_alignment.offset}, grain: {optimal_alignment.grainSize}")
420

421
# Create geometry for alignment operations
422
geometry = parted.Geometry(device, start=0, length=device.length)
423

424
# Align a sector value
425
unaligned_sector = 1000
426
aligned_up = optimal_alignment.alignUp(geometry, unaligned_sector)
427
aligned_down = optimal_alignment.alignDown(geometry, unaligned_sector)
428
aligned_nearest = optimal_alignment.alignNearest(geometry, unaligned_sector)
429

430
print(f"Original sector: {unaligned_sector}")
431
print(f"Aligned up: {aligned_up}")
432
print(f"Aligned down: {aligned_down}")
433
print(f"Aligned nearest: {aligned_nearest}")
434

435
# Check if sector is aligned
436
is_aligned = optimal_alignment.isAligned(geometry, aligned_up)
437
print(f"Aligned up sector is properly aligned: {is_aligned}")
438
```
439

440
### Creating Aligned Partitions
441

442
```python
443
import parted
444

445
device = parted.getDevice('/dev/sdb')
446
disk = parted.newDisk(device)
447

448
# Get optimal alignment for performance
449
alignment = device.getOptimumAlignment()
450

451
# Create geometry for entire device
452
device_geometry = parted.Geometry(device, start=0, length=device.length)
453

454
# Calculate aligned start for new partition
455
# Start after any existing partitions, aligned optimally
456
desired_start = 2048  # Common starting point
457
aligned_start = alignment.alignUp(device_geometry, desired_start)
458

459
# Calculate size (10GB) and align the end
460
size_sectors = (10 * 1024**3) // device.sectorSize
461
desired_end = aligned_start + size_sectors - 1
462
aligned_end = alignment.alignDown(device_geometry, desired_end)
463

464
# Create aligned geometry
465
aligned_geometry = parted.Geometry(
466
    device, 
467
    start=aligned_start, 
468
    end=aligned_end
469
)
470

471
print(f"Aligned partition: sectors {aligned_start} to {aligned_end}")
472
print(f"Size: {aligned_geometry.length * device.sectorSize / (1024**3):.2f} GB")
473

474
# Create partition with aligned geometry
475
partition = parted.Partition(
476
    disk=disk,
477
    type=parted.PARTITION_NORMAL,
478
    geometry=aligned_geometry
479
)
480

481
# Use constraint for adding partition
482
constraint = device.getOptimalAlignedConstraint()
483
disk.addPartition(partition, constraint)
484
disk.commit()
485
```
486

487
### Alignment Intersection
488

489
```python
490
import parted
491

492
device = parted.getDevice('/dev/sda')
493

494
# Get different alignment requirements
495
min_alignment = device.getMinimumAlignment()
496
opt_alignment = device.getOptimumAlignment()
497

498
# Create intersection of alignments
499
combined_alignment = min_alignment.intersect(opt_alignment)
500

501
print(f"Minimum alignment: offset={min_alignment.offset}, grain={min_alignment.grainSize}")
502
print(f"Optimal alignment: offset={opt_alignment.offset}, grain={opt_alignment.grainSize}")
503
print(f"Combined alignment: offset={combined_alignment.offset}, grain={combined_alignment.grainSize}")
504

505
# Use combined alignment for operations
506
geometry = parted.Geometry(device, start=0, length=device.length)
507
test_sector = 4096
508
aligned_sector = combined_alignment.alignUp(geometry, test_sector)
509
print(f"Sector {test_sector} aligned to {aligned_sector}")
510
```
511

512
## Alignment Types
513

514
Different alignment requirements serve different purposes:
515

516
### Minimum Alignment
517
- Required for device to function correctly
518
- Usually matches physical sector size
519
- Obtained via `device.getMinimumAlignment()`
520

521
### Optimal Alignment  
522
- Provides best performance
523
- Often aligns to large boundaries (1MB, etc.)
524
- Obtained via `device.getOptimumAlignment()`
525

526
### Custom Alignment
527
- User-defined alignment requirements
528
- Can be intersected with device alignments
529
- Created with specific offset and grain size values
530

531
## Performance Considerations
532

533
Proper alignment is crucial for:
534
- **SSD Performance**: Aligning to erase block boundaries
535
- **RAID Performance**: Aligning to stripe boundaries  
536
- **4K Sectors**: Avoiding read-modify-write penalties
537
- **Flash Storage**: Minimizing wear and maximizing speed