How to compile

First, you must decompress the file packing-ellipsoids.tar.gz that you have downloaded.

tar -zxvf packing-ellipsoids.tar.gz

It will create a directory called packing-ellipsoids. Enter this directory and type make to compile the code:

cd packing-ellipsoids
make

After the compilation, an executable file called packEllipsoids will be created in the current directory.

Defining your own problem

In order to solve your own problem, you must set a few options. These options must be set in a file of your choice. For example, you could put the options in a file called packing.opt.

Ellipsoids

The first option you should set is called NUMBER_OF_ELLIPSOIDS. This option defines the number of ellipsoids to be packed and must be followed by an integer number. Therefore, if you want to pack 100 ellipsoids, you should add the following line in the options file:

NUMBER_OF_ELLIPSOIDS 100

Next, you should define the dimensions of the ellipsoids to be packed. If the ellipsoids you want to pack are all identical, then you can use the IDENTICAL_ELLIPSOIDS option. This option must be followed by three numbers, which are the lengths of the semi-axes of the ellipsoids. For example, if you want to pack ellipsoids with semi-axis lengths 5, 3 and 2.7, you should append the following line to the options file:

IDENTICAL_ELLIPSOIDS 5 3 2.7

If the ellipsoids you want to pack are non-identical, you can provide a file describing the semi-axis lengths of each ellipsoid. To specify the file that contains the lengths of the semi-axes of the ellipsoids, use the ELLIPSOID_DIMENSIONS_FILE_NAME option. For example, if the file containing this information is called ellipsoids.txt, then you should add the following line to the options file:

ELLIPSOID_DIMENSIONS_FILE_NAME ellipsoids.txt

This file must have the following format.

m
a1 b1 c1
a2 b2 c2
...
am bm cm

The first line must contain an integer number m which is the number of ellipsoids. Then, each one of the next m lines must contain the lengths of the semi-axes (a, b, c) of an ellipsoid. For example, if you want to pack 3 ellipsoids where the first one has semi-axis lengths 4.1, 3.2 and 1.1, the second one has semi-axis lengths 2.3, 2.3 and 2.1, and the third one has semi-axis lengths 5.6, 3.3 and 3.3, your file would have the following content:

3
4.1 3.2 1.1
2.3 2.3 2.1
5.6 3.3 3.3

Container

You should also specify the type of container where the ellipsoids will be packed in. You can choose either an sphere or a cuboid as the container. To pack the ellipsoids within an sphere centered at the origin, you should use the SPHERE_CONTAINER option. To pack the ellipsoids within a rectangular cuboid, you should use the CUBOID_CONTAINER option. The rectangular cuboid is centered at the origin and has its sides parallel to the coordinate axes. These options do not require any further information.

If you want to pack the ellipsoids inside a minimizing volume container, you must use the MINIMIZE_VOLUME option. This option does not require any further information.

If you do not want to minimize the volume of the container or if you want to provide an initial guess for the radius of the sphere or the lengths of the sides of the cuboid, you must use the options SPHERE_CONTAINER_RADIUS or CUBOID_CONTAINER_SIDE_LENGTHS. To provide the radius of the sphere, use the SPHERE_CONTAINER_RADIUS option, which must be followed by a number which is the radius of the sphere. For example, if the sphere must have radius 20.75, you should add the following line to the options file:

SPHERE_CONTAINER_RADIUS 20.75

To provide the lengths of the sides of the rectangular cuboid, use the CUBOID_CONTAINER_SIDE_LENGTHS option. This option must be followed by three numbers which are the length of the side parallel to the x-axis, the length of the side parallel to the y-axis, and the length of the side parallel to the z-axis, respectively. For example, if the cuboid must have side lengths 6, 5.7 and 4, you should add the following line to the options file:

CUBOID_CONTAINER_SIDE_LENGTHS 6 5.7 4

Initial configuration

You can provide an initial configuration of the ellipsoids through the INITIAL_CONFIGURATION option. This option must be followed by the name of the file containing the initial arrangement of the ellipsoids. The content of this file must have the following format.

m
a1 b1 c1 x1 y1 z1 t1 u1 v1
a2 b2 c2 x2 y2 z2 t2 u2 v2
...
am bm cm xm ym zm tm um vm

The first line must contain the number m of ellipsoids. Then, each one of the next m lines must contain the lengths of the semi-axes (a, b, c), the center (x, y, z) and the rotations angles (t, u, v) of an ellipsoid. We have adopted a left-handed coordinate system and the ellipsoids are rotated through an angle t about the x-axis, through an angle u about the y-axis, and through an angle v about the z-axis, in this order.

For example, we could provide the following initial configuration for three ellipsoids in a file named initial-configuration.txt:

3
4.1 3.2 1.1 0.0  1.0  2.0  0.50 1.57  3.1415
2.3 2.3 2.1 3.3  4.1  5.9 -0.25 2.32 -0.7010
5.6 3.3 3.3 1.0 -3.1 -1.1  1.32 0.76  1.4562

In this example, the first ellipsoid has semi-axis lengths 4.1, 3.2 and 1.1, is centered at the point (0.0, 1.0, 2.0) and has rotation angles 0.5, 1.57 and 3.1415. Then, you should append the following line to your options file:

INITIAL_CONFIGURATION initial-configuration.txt

How to run

In order to run the software, simply type the name of the executable file and the name of the options file. If your options file is called packing.opt for example, then you should execute the program as:

./packEllipsoids packing.opt

Solution output

By default, the solution is saved in a file named solution.txt. The format of the file is the same as the one described in the solutions page. To change the name of the output file, you can use the OUTPUT_FILE_NAME option. For example, if you want the output file to be named output.txt, you should add the following line to your options file.

OUTPUT_FILE_NAME output.txt