. And, of course, you will have to be able to store the original data sets, currently 32 GB each... get yourself a pile of cheap external drives for that.While the installation is described detailed in the manual (section "Installation"), the overall procedure will be described here as well. If you encounter any problems during installation, do not hesitate to contact me. I will try to help out as good as I can. However, it is important to know that I am by training no software specialist or Linux expert. I may meet my limits, too. However, I will post any questions in the FAQ section, ideally with a solution. Otherwise, I would be glad if anyone out there who knows better than me what to do could comment - I will upload these answers as well as they may he helpful to the community.
I am using Linux - Kubuntu, to be precise - and I am going to describe the installation for this system. I have no idea what one has to modify if one wants to install it in a Windows or Macintosh environment, although this should be relatively easy for experienced users of these operating systems.
For proper choice of your computer, be aware that we are dealing with large amounts of data to be processed. This means that you can never have enough RAM (I am using 64 GBytes of RAM in a 24 core machine - however, you should be able to use the program starting from 8 GB). The number of cores is not the limiting factor, the speed is mostly determined by the reading speed of your data carrier. To read (and process on-the-fly) 32 GB of data it takes between 10 and 30 minutes per data set. The program comes with a batch routine, so you can preprocess your data over night and the use the reduced data sets (see below) the next morning, which works very fast. Once the preprocessing is done, everything is much faster. Nevertheless, it is advisable to use as fast mass storage devices as possible, in my case 4TB SSD drives - makes life much more convenient... - however, don't get scared, the program will work with much less resources, you'll only have to wait longer . And, of course, you will have to be able to store the original data sets, currently 32 GB each... get yourself a pile of cheap external drives for that.
Of course, you are absolutely free to choose any directory according to your personal preferences. However, If you need help by me, it is highly advisable to use the same conventions as I do, which will make any problem solving much easier. For inexperienced Linux users, please note that in general the system files are in the so-called root directory, which you will not have to access. Within the root directory, there is a /home directory, which is the location where different users will have their individual directory structures, in my case it is /home/joe, which in your case would be /home/*your_user_name*. The equivalent to the Windows file explorer is called "Dolphin" and can be found in the KDE Menu, resembling a file container (blue)). It can also be found in the fourth sub-menu from top (in German: Dienstprogramme, meaning service programs - the order may vary in other languages....).
If you decide to use my environment, you should first download a recent Kubuntu so-called "live CD", which allows you to try Kubuntu but also to install it - I recommend to choose a "LTS" version, which ensures long time support of 3 years. Other variants of the "Ubuntu" family like pure Ubuntu or Lubuntu probably work as well, but I have not tested them. If you do not have a separate computer to install, you may as well use a virtual box (e.g.VirtualBox by Oracle), for your machine which allows you to run other operating systems in a separate window, the virtual box.
After you successfully installed Kubuntu on your computer, you will need to make sure that C++ is installed, which is usually the GNU C++ variant gcc. Open a console window\ (Use "Alt-F2" and type "console" in the appearing mini window on top of the screen, followed by a return. Alternatively you can use "console" from the system tab in KDE's application start menu, left lower corner, equivalent to Windows' "Start" button) and type "whereis gcc" (without the quotation marks) followed by a return.
If you see something like "gcc: /usr/bin/gcc /usr/lib/gcc /usr/share/man/man1/gcc.1.gz" everything is already installed. Otherwise use "Discover" (This is a standard software installation program available under the system tab in the KDE Menu, left lower corner, equivalent to Windows' "Start" button) to search for and install gcc.
As you will be using a powerful software called "QtCreator" you need to download and install this software now. From the website you see that it is available as Open Source software, but also as a commercial product. Read carefully the license conditions, especially if you want to use the OpenSource variant, as it contains a number of obligations (Contribution via Open Source).
When selecting an open source license for your project, you contribute to free and open source software development by using Qt under any of the following licenses:
Please note that there are parts of Qt that are only provided under GPL for open source users that will require you to license your application under a GPL compatible license. Qt also ships with third party open source components that might require respective licensing compliancy, if used. See details of other licenses inside Qt.
To install the software you first need an account (follow instructions on the website) and then you are able to download an installer which will then install the software for you - this may take a while, as it is quite powerful!
My suggestion for installation is to place it in "/home/*your_user_name*/Qt, as you will be asked where to place the files. I also suggest to keep the same order of directories and subdirectories, as it will make it easier to be helped, if necessary.
Once the installation is completed, you will need to install a graphics library (libGL), which is not yet included. For this, open a console again and type
"sudo apt-get install libglu1-mesa-dev freeglut3-dev mesa-common-dev"
followed by
"sudo ln /usr/lib/libGL.so.1 /usr/lib/libGL.so"
The last line seems to be valid if you use an NVIDIA graphics card only, for others, try
"sudo ln -s /usr/lib/ /usr/lib/libGL.so.1" or "sudo ln -s /usr/lib/ /usr/lib/libGL.so"
Although I am not an expert here, this command seems to create a symbolic link in Linux, meaning that it "tells" the operating system that searches for the library file in /usr/lib/ to also search the directory /usr/lib/libGL.so etc.
With the command "sudo" you allow modifications / installations to the system on a superuser level, which implies that you are asked for your user password after you hit return.
As 4DSTEMDEx uses Fast Fourier Transforms (currently only for 2D integration in Fourier space), you will have to install another package (FFTW3 -- "the fastest Fourier transform of the west").
I suggest to download the zip file to "/home/*your_user_name*/FFTW3". Unpack the zip file (in Dolphin, right-click on the file and choose "decompress" (or a similar phrase in your language), which will cause the creation of a new directory with the same name as the file, and all files put in it including all the sub-directories.
Again, observe the license conditions (GNU General Public License).
Move into the directory with the unpacked files and follow the installation guide in the README file. As 4DSTEMDEx supports multithreaded Fast Fourier transforms, you MUST use
"sudo ./configure --enable-threads" instead of the simple "./configure" command, followed by "sudo make" and then "sudo make install" all written in a console opened in the directory where you unzipped FFTW3 to. Especially the make and make install commands may take some time, depending on the speed of your machine (tens of seconds to minutes).
Please note the essential use of a blank space after configure and the double dash in front of enable!
Move to your home directory "/home/*your_user_name*/" and create a subdirectory "/home/*your_user_name*/QtCreator/4DSTEMDEx". Navigate into this subdirectory and unzip all source files provided by me into it. Then click on the project file "4DSTEMDEx.pro" - this should now open QtCreator. If this does not happen, try to start QtCreator and within the program open "4DSTEMDEx.pro"
Once QtCreator is started up, you should be ready to go. On the left you find all source files and headers. To start the program, all you have to do is to press the green triangular button to the lower left or simply "Ctrl-R". Once you successfully compiled the source code, you may simply start the ready-to-run program in a console by typing (in the correct directory) "./4DSTEMDEx" or by clicking on it with the mouse. I am not sure, but this may work even if you did not compile the program yourself, but if all the necessary libraries are installed in the right places. If it does not start right away, try to reboot your system, as some previous installations will need a restart before they are known to the system. You may also want to check the "4DSTEMDEx.pro" file (upper left corner, below the bold "4DSTEMDEx" - click on it to see the contents. Make sure that the lines
"QMAKE_CXXFLAGS += -pthread" and "LIBS += -lfftw3_threads -lfftw3 -lm -lpthread"
are present -- they take care that QtCreator is able to locate the FFTW3 libraries and a library necessary for multithreading.
After you opened the 4DSTEMDEx.pro file in QtCreator, you should see the project view. Once everything is configured ok, it should now be sufficient to press the green triangular button to the lower left or simply "Ctrl-R", which both start the compilation and linking process. Another much less painful and dangerous\footnote{By dangerous it is meant that it is easily the case to unintendedly modify some lines of code, if the mouse is in the window and you type something which is meant to go elsewhere, or -- even worse -- you delete parts of the code by chance. To prevent this you might consider to execute the program directly as described in the next few sentences.} option might be to simply copy the executable file 4DSTEMDEx into the 4DSTEMDEx directory and start the executable direct. This can be done with a simple click on the executable's name, but only if it is marked as executable. To do this, left-click on the executable file, go to "Properties" and then click the tab "Rights Management" (or similar). There you can click on a checkbox making the file executable. Close the window and click on the 4DSTEMDEx file to execute.
Another way to allow the file to be executed is to open a console, move to the folder holding the executable file which is still not allowed to be executed and type in the console "sudo chmod +x 4DSTEMDEx" - afterwards, it is permanently set as executable, until you replace it with a newer version (for security reasons, freshly downloaded files usually are automatically set as non-executable). Good luck!