CUBETRANSPORT

cubetransport

Description of cubetransport

cubetransport is a software by myself which computes the optimal transportation distance between two electronic densities given as .cube files sharing the same grid.

Download

Here are the source codes.

How to compile

This program is written in C language, using the ISO/CEI 9899:1999 standard (option -std=c99 with GCC). The mathematical library has to be linked (option -lm with GCC). So, after having decompressed the files in some (previously empty) working directory, on a UNIX system equipped with GCC, enter in command-line:
gcc -std=c99 *.c -lm -o cubetransport

User's instructions

The syntax for use is:
./cubetransport file1.cube file2.cube [-m=MODE] [-p=PRECISION] [-l=LOGFILE]
where file1.cube and file2.cube are the (access paths to) .cube files, LOGFILE is the chosen log file name, and:

MODE is the transportation mode chosen. There are four possibilities which are resp. tv, kr (the default), lq and qw, for resp. total variation, W₁ Wasserstein distance, linearized W₂ Wasserstein distance, and actual W₂ Wasserstein distance.
PRECISION is to set the computations' precision. For modes kr and qw, the default precision (corresponding to PRECISION being 0) takes much time indeed... Specifying -p=-1 asks for a twice less precise result, which allows to speed up computation (by a factor depending on the transportation mode); specifying -p=-2 asks for a result 4 times less precise, etc.. A fractional or positive precision can also be specified.

metacube

cubetransport comes with a small utility program called metacube. metacube takes a .cube file with high precision and transforms it into a new .cube file with a coarser grid. This is useful because .cube files normally describe punctual densities, while cubetransport is devised to work with volumic densities; and the best way to get precise volumic data is to start from high-precision punctual data. (Note however that in any case, cubetransport automatically applies [virtually] metacube with the defaults parameters before starting computations).

Here are the source codes for metacube. You compile metacube in the same way as transcube.

The syntax for use is:
./metacube [-p] [-v] [-k=K] input.cube [-o=output.cube] -w
where input.cube is the input file name, and:

-p means that the input file describes punctual densities at the nodes of the lattice; while -v means that the densities given are mean (volumic) densities on the small cubes centered at the lattice's nodes. Options -p and -v obviously cannot be used together. If neither option is specified, the program chooses the right one in a clever way.
K (blocK size) in how many small cubes you want to group together along each direction. So, the number of nodes will be divided by (roughly) K³.
output.cube is the chosen output file name; while option -w is to overwrite the file (in this case a backup file [whose name ends with ‘~’] is generated). Options -o and -w can obviously not be used together. If none of these options is specified, the output name is chosen automatically.