Skip to content

cylinder

Bases: geometric_space

Represents a cylindrical geometry in a 3D space.

This class defines a cylinder centered at a specific coordinate in a 3D space with configurable radius, depth, and packing strategies.

Attributes:

Name Type Description
p_r int

Radius of the cylinder's base.
p_d int

Depth extending backward from the center along the cylinder's axis.
p_d_prime int

Depth extending forward from the center along the cylinder's axis.
center coordinate_3d

The center coordinate of the cylinder.
name str

The name of the cylindrical geometry.
Source code in tinybig/koala/geometry/cylinder.py 
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
class cylinder(geometric_space):
    """
        Represents a cylindrical geometry in a 3D space.

        This class defines a cylinder centered at a specific coordinate in a 3D space
        with configurable radius, depth, and packing strategies.

        Attributes
        ----------
        p_r : int
            Radius of the cylinder's base.
        p_d : int
            Depth extending backward from the center along the cylinder's axis.
        p_d_prime : int
            Depth extending forward from the center along the cylinder's axis.
        center : coordinate_3d
            The center coordinate of the cylinder.
        name : str
            The name of the cylindrical geometry.
    """
    def __init__(
        self,
        p_r: int, p_d: int = 0, p_d_prime: int = None,
        center: coordinate_3d = coordinate_3d(0, 0, 0),
        name: str = 'cylinder_geometry',
        *args, **kwargs
    ):
        """
            Initializes the cylindrical geometry.

            Parameters
            ----------
            p_r : int
                Radius of the cylinder's base.
            p_d : int, optional
                Depth extending backward from the center along the cylinder's axis (default is 0).
            p_d_prime : int, optional
                Depth extending forward from the center along the cylinder's axis (default is equal to `p_d`).
            center : coordinate_3d, optional
                The center coordinate of the cylinder (default is coordinate_3d(0, 0, 0)).
            name : str, optional
                The name of the cylindrical geometry (default is 'cylinder_geometry').
            *args, **kwargs
                Additional arguments for customization.
        """
        self.p_r = p_r
        self.p_d = p_d
        self.p_d_prime = p_d_prime if p_d_prime is not None else p_d
        super().__init__(center=center, name=name, *args, **kwargs)

    def radius(self):
        """
            Returns the radius of the cylinder's base.

            Returns
            -------
            int
                The radius of the cylinder's base.
        """
        return self.p_r

    def depth(self):
        """
            Calculates the total depth of the cylinder.

            Returns
            -------
            int
                The total depth of the cylinder, including both forward and backward extensions.
        """
        return self.p_d + self.p_d_prime + 1

    @staticmethod
    def get_packing_strategies():
        """
            Returns the available packing strategies for the cylinder.

            Returns
            -------
            list
                A list of packing strategies:
                ['sparse_square', 'complete_square', 'sparse_hexagonal',
                 'complete_hexagonal', 'dense_hexagonal', 'denser_hexagonal', 'densest_packing'].
        """
        return [
            'sparse_square', 'complete_square',
            'sparse_hexagonal', 'complete_hexagonal', 'dense_hexagonal', 'denser_hexagonal',
            'densest_packing',
        ]

    def packing_strategy_parameters(self, packing_strategy: str = 'complete_square', *args, **kwargs):
        """
            Determines the center distances for packing based on the selected strategy.

            Parameters
            ----------
            packing_strategy : str, optional
                The packing strategy to use (default is 'complete_square').
                Options include:
                - 'sparse_square': Centers are 2 times the radius apart.
                - 'complete_square': Centers are sqrt(2) times the radius apart.
                - 'sparse_hexagonal': Centers are sqrt(3) times the radius apart.
                - 'complete_hexagonal': Centers are 1.5 times and sqrt(3) times the radius apart.
                - 'dense_hexagonal': Centers are sqrt(6)/2 and sqrt(2) times the radius apart.
                - 'denser_hexagonal': Centers are sqrt(3)/2 and the radius apart.
                - 'densest_packing': Centers are 1 unit apart.

            *args, **kwargs
                Additional arguments for customization.

            Returns
            -------
            tuple
                A tuple (cd_h, cd_w, cd_d) representing the center distances for height, width, and depth.

            Raises
            ------
            ValueError
                If an unknown packing strategy is provided.
        """
        if packing_strategy == 'sparse_square':
            cd_h, cd_w, cd_d = 2 * self.p_r, 2 * self.p_r, 2 * self.p_d
        elif packing_strategy == 'complete_square':
            cd_h, cd_w, cd_d = math.sqrt(2) * self.p_r, math.sqrt(2) * self.p_r, 2 * self.p_d

        elif packing_strategy == 'sparse_hexagonal':
            cd_h, cd_w, cd_d = math.sqrt(3) * self.p_r, 2 * self.p_r, 2 * self.p_d
        elif packing_strategy == 'complete_hexagonal':
            cd_h, cd_w, cd_d = 1.5 * self.p_r, math.sqrt(3) * self.p_r, 2 * self.p_d
        elif packing_strategy == 'dense_hexagonal':
            cd_h, cd_w, cd_d = 0.5 * math.sqrt(6) * self.p_r, math.sqrt(2) * self.p_r, self.p_d
        elif packing_strategy == 'denser_hexagonal':
            cd_h, cd_w, cd_d = 0.5 * math.sqrt(3) * self.p_r, self.p_r, self.p_d

        elif packing_strategy == 'densest_packing':
            cd_h, cd_w, cd_d = 1, 1, 1
        else:
            warnings.warn(f'Unknown strategy {packing_strategy}, will use the default densest_packing strategy...')
            cd_h, cd_w, cd_d = 1, 1, 1

        cd_h, cd_w, cd_d = max(int(cd_h), 1), max(int(cd_w), 1), max(int(cd_d), 1)
        return cd_h, cd_w, cd_d

    def generate_coordinates(self, *args, **kwargs):
        """
            Generates the coordinates of all points within the cylinder.

            Parameters
            ----------
            *args, **kwargs
                Additional arguments for customization.

            Returns
            -------
            dict
                A dictionary where keys are coordinates within the cylinder
                and values are indicators (default is 1).
        """
        coordinates = {}
        for i in range(-self.p_r, self.p_r+1):
            j_lim = int(math.sqrt(self.p_r ** 2 - i ** 2))
            for j in range(-j_lim, j_lim + 1):
                if i**2 + j**2 <= self.p_r**2:
                    for k in range(-self.p_d_prime, self.p_d_prime+1):
                        coord = coordinate_3d(i, j, k)
                        coordinates[coord + self.center] = 1
        return coordinates

__init__(p_r, p_d=0, p_d_prime=None, center=coordinate_3d(0, 0, 0), name='cylinder_geometry', *args, **kwargs)

Initializes the cylindrical geometry.

Parameters:

Name Type Description Default
p_r int

Radius of the cylinder's base.

 required
p_d int

Depth extending backward from the center along the cylinder's axis (default is 0).

 0
p_d_prime int

Depth extending forward from the center along the cylinder's axis (default is equal to p_d).

 None
center coordinate_3d

The center coordinate of the cylinder (default is coordinate_3d(0, 0, 0)).

 coordinate_3d(0, 0, 0)
name str

The name of the cylindrical geometry (default is 'cylinder_geometry').

 'cylinder_geometry'
*args

Additional arguments for customization.

 ()
**kwargs

Additional arguments for customization.

 ()
Source code in tinybig/koala/geometry/cylinder.py 
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
def __init__(
    self,
    p_r: int, p_d: int = 0, p_d_prime: int = None,
    center: coordinate_3d = coordinate_3d(0, 0, 0),
    name: str = 'cylinder_geometry',
    *args, **kwargs
):
    """
        Initializes the cylindrical geometry.

        Parameters
        ----------
        p_r : int
            Radius of the cylinder's base.
        p_d : int, optional
            Depth extending backward from the center along the cylinder's axis (default is 0).
        p_d_prime : int, optional
            Depth extending forward from the center along the cylinder's axis (default is equal to `p_d`).
        center : coordinate_3d, optional
            The center coordinate of the cylinder (default is coordinate_3d(0, 0, 0)).
        name : str, optional
            The name of the cylindrical geometry (default is 'cylinder_geometry').
        *args, **kwargs
            Additional arguments for customization.
    """
    self.p_r = p_r
    self.p_d = p_d
    self.p_d_prime = p_d_prime if p_d_prime is not None else p_d
    super().__init__(center=center, name=name, *args, **kwargs)

depth()

Calculates the total depth of the cylinder.

Returns:

Type Description
int

The total depth of the cylinder, including both forward and backward extensions.
Source code in tinybig/koala/geometry/cylinder.py 
76
77
78
79
80
81
82
83
84
85
def depth(self):
    """
        Calculates the total depth of the cylinder.

        Returns
        -------
        int
            The total depth of the cylinder, including both forward and backward extensions.
    """
    return self.p_d + self.p_d_prime + 1

generate_coordinates(*args, **kwargs)

Generates the coordinates of all points within the cylinder.

Parameters:

Name Type Description Default
*args

Additional arguments for customization.

 ()
**kwargs

Additional arguments for customization.

 ()

Returns:

Type Description
dict

A dictionary where keys are coordinates within the cylinder and values are indicators (default is 1).
Source code in tinybig/koala/geometry/cylinder.py 
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
def generate_coordinates(self, *args, **kwargs):
    """
        Generates the coordinates of all points within the cylinder.

        Parameters
        ----------
        *args, **kwargs
            Additional arguments for customization.

        Returns
        -------
        dict
            A dictionary where keys are coordinates within the cylinder
            and values are indicators (default is 1).
    """
    coordinates = {}
    for i in range(-self.p_r, self.p_r+1):
        j_lim = int(math.sqrt(self.p_r ** 2 - i ** 2))
        for j in range(-j_lim, j_lim + 1):
            if i**2 + j**2 <= self.p_r**2:
                for k in range(-self.p_d_prime, self.p_d_prime+1):
                    coord = coordinate_3d(i, j, k)
                    coordinates[coord + self.center] = 1
    return coordinates

get_packing_strategies() staticmethod

Returns the available packing strategies for the cylinder.

Returns:

Type Description
list

A list of packing strategies: ['sparse_square', 'complete_square', 'sparse_hexagonal', 'complete_hexagonal', 'dense_hexagonal', 'denser_hexagonal', 'densest_packing'].
Source code in tinybig/koala/geometry/cylinder.py 
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
@staticmethod
def get_packing_strategies():
    """
        Returns the available packing strategies for the cylinder.

        Returns
        -------
        list
            A list of packing strategies:
            ['sparse_square', 'complete_square', 'sparse_hexagonal',
             'complete_hexagonal', 'dense_hexagonal', 'denser_hexagonal', 'densest_packing'].
    """
    return [
        'sparse_square', 'complete_square',
        'sparse_hexagonal', 'complete_hexagonal', 'dense_hexagonal', 'denser_hexagonal',
        'densest_packing',
    ]

packing_strategy_parameters(packing_strategy='complete_square', *args, **kwargs)

Determines the center distances for packing based on the selected strategy.

Parameters:

Name Type Description Default
packing_strategy str

The packing strategy to use (default is 'complete_square'). Options include: - 'sparse_square': Centers are 2 times the radius apart. - 'complete_square': Centers are sqrt(2) times the radius apart. - 'sparse_hexagonal': Centers are sqrt(3) times the radius apart. - 'complete_hexagonal': Centers are 1.5 times and sqrt(3) times the radius apart. - 'dense_hexagonal': Centers are sqrt(6)/2 and sqrt(2) times the radius apart. - 'denser_hexagonal': Centers are sqrt(3)/2 and the radius apart. - 'densest_packing': Centers are 1 unit apart.

 'complete_square'
*args

Additional arguments for customization.

 ()
**kwargs

Additional arguments for customization.

 ()

Returns:

Type Description
tuple

A tuple (cd_h, cd_w, cd_d) representing the center distances for height, width, and depth.

Raises:

Type Description
ValueError

If an unknown packing strategy is provided.
Source code in tinybig/koala/geometry/cylinder.py 
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
def packing_strategy_parameters(self, packing_strategy: str = 'complete_square', *args, **kwargs):
    """
        Determines the center distances for packing based on the selected strategy.

        Parameters
        ----------
        packing_strategy : str, optional
            The packing strategy to use (default is 'complete_square').
            Options include:
            - 'sparse_square': Centers are 2 times the radius apart.
            - 'complete_square': Centers are sqrt(2) times the radius apart.
            - 'sparse_hexagonal': Centers are sqrt(3) times the radius apart.
            - 'complete_hexagonal': Centers are 1.5 times and sqrt(3) times the radius apart.
            - 'dense_hexagonal': Centers are sqrt(6)/2 and sqrt(2) times the radius apart.
            - 'denser_hexagonal': Centers are sqrt(3)/2 and the radius apart.
            - 'densest_packing': Centers are 1 unit apart.

        *args, **kwargs
            Additional arguments for customization.

        Returns
        -------
        tuple
            A tuple (cd_h, cd_w, cd_d) representing the center distances for height, width, and depth.

        Raises
        ------
        ValueError
            If an unknown packing strategy is provided.
    """
    if packing_strategy == 'sparse_square':
        cd_h, cd_w, cd_d = 2 * self.p_r, 2 * self.p_r, 2 * self.p_d
    elif packing_strategy == 'complete_square':
        cd_h, cd_w, cd_d = math.sqrt(2) * self.p_r, math.sqrt(2) * self.p_r, 2 * self.p_d

    elif packing_strategy == 'sparse_hexagonal':
        cd_h, cd_w, cd_d = math.sqrt(3) * self.p_r, 2 * self.p_r, 2 * self.p_d
    elif packing_strategy == 'complete_hexagonal':
        cd_h, cd_w, cd_d = 1.5 * self.p_r, math.sqrt(3) * self.p_r, 2 * self.p_d
    elif packing_strategy == 'dense_hexagonal':
        cd_h, cd_w, cd_d = 0.5 * math.sqrt(6) * self.p_r, math.sqrt(2) * self.p_r, self.p_d
    elif packing_strategy == 'denser_hexagonal':
        cd_h, cd_w, cd_d = 0.5 * math.sqrt(3) * self.p_r, self.p_r, self.p_d

    elif packing_strategy == 'densest_packing':
        cd_h, cd_w, cd_d = 1, 1, 1
    else:
        warnings.warn(f'Unknown strategy {packing_strategy}, will use the default densest_packing strategy...')
        cd_h, cd_w, cd_d = 1, 1, 1

    cd_h, cd_w, cd_d = max(int(cd_h), 1), max(int(cd_w), 1), max(int(cd_d), 1)
    return cd_h, cd_w, cd_d

radius()

Returns the radius of the cylinder's base.

Returns:

Type Description
int

The radius of the cylinder's base.
Source code in tinybig/koala/geometry/cylinder.py 
65
66
67
68
69
70
71
72
73
74
def radius(self):
    """
        Returns the radius of the cylinder's base.

        Returns
        -------
        int
            The radius of the cylinder's base.
    """
    return self.p_r