SudoDEM Tutorial Series: From Preparation to Installation

SudoDEM is developed based on the Linux platform and provides binary installation (compressed) packages for Ubuntu distributions (14.04-18.04). Simply extract and use without root permissions, no writing to system core directories, completely “green”. In the later stages of the project, Singularity container binary packages will be provided for any Linux distribution.

if you are a programming beginner or Linux beginner:
  it is recommended to try the compiled binary package first
  please continue reading this article
else:
  you can directly download the source code for compilation
  you can quickly skip this article

If you can easily understand the meaning expressed in the code block above, then you can continue reading, otherwise, please directly scroll to the end of the article and like it.

To use SudoDEM, you only need to master the most basic Linux system knowledge and Python programming skills. This article will introduce these essential knowledge. First, please prepare a Linux system, Ubuntu 14-18 is recommended; you can get a Linux system through the following options:

Install virtual machine on Windows (for heavy Windows users, experience Linux)
Enable Linux subsystem on Windows 10 (for heavy Windows users, experience Linux)
Install multi-system coexisting with Windows (requires restarting computer to switch systems)
Install single system, such as Deepin (for light Windows users)
Install single system, such as Ubuntu (for heavy Linux users)

[Basic Linux Commands]

Taking Ubuntu system as an example (commands may vary slightly for different Linux distributions such as CentOS), here are the most basic commands and shortcuts:

Open terminal (terminal, i.e., command line window): CTRL+ALT+T
Install software to system: sudo apt-get install package or sudo apt install package
Display current path (working directory): pwd
Change path (working directory): cd directory

The path/directory can be a relative path or absolute path.

Among them, the absolute path starts from the Linux root directory (/), such as: /bin, /home/sway, etc. To facilitate access to user directories (such as /home/sway/), the system gives an abbreviated directory for user directories, represented as ~; ~ is equivalent to the aforementioned /home/sway. Note that Linux system is naturally multi-user, allowing multiple users to log in to the same system at the same time (but each has their own running environment, these configurations are saved in their respective user directories; note: “simultaneous login” does not mean accessing the same desktop). For example, user sway has logged into the system for work, user SC can enter the system through the network (such as ssh remote login command) to work; different users do not interfere with each other (except for competing for hardware resources, such as everyone using SudoDEM for calculations). Relative paths are based on a specific directory. Strictly speaking, paths based on the root directory can also be called relative paths. Because there is never absolute (). In addition to the root directory marker (/) and user directory marker (~), there are two specific symbols used for relative paths (one dot . and two dots ..). One dot (.) represents the current working path, which is the path seen after executing pwd; two dots (..) represent the parent directory relative to the current path. For example, cd ../sub means switching the path to the subdirectory under the parent directory; cd ../../ means switching to the parent directory of the parent directory; cd ./sub switches to the subdirectory under the current directory, of course you can directly type cd sub. Run executable file (program) prog: prog or ./path/prog. If prog can be recognized by the terminal, that is, prog has been added to the system search path (generally the PATH environment variable), you only need to type the executable file name (such as the aforementioned cd is a system command, already in the system default search path). Otherwise, you need to add the path of prog (here ./ means executing this file).

Force terminate terminal program: CTRL+C

$> sudo apt−get install python−numpy
$> pwd
$> cd /home/
$> sudodem3d

[Python 2.7]

Python and C++ mixed programming is the current mainstream trend in computational software. Among them, Python mainly plays the role of interface calling, achieving rapid modeling; while the heavy core computing part is implemented by underlying C++ computing modules. SudoDEM currently still uses Python 2.7 version, and subsequent project development and upgrades will use Python 3.0+ version. It should be pointed out that Python 3 is a comprehensive upgrade of Python 2 and is not backward compatible, but in SudoDEM, we only need the most basic functions (basic syntax is still consistent). The following Python script shows the most basic introductory knowledge.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
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


import math # import the module math which includes some basic math functions

# we have numbers
a = 2 # integer number
b = 5
c = 2.0 # float number
d = a/b # the value is an integer
e = c/b # float number
print a, d, e # print the values of a, d and e to the terminal

#we have strings
a = 'abc' # we can assign any type of values to any type of variables
b = "this is a 'Python' script."
print a, b

#we have list, tuple and dict to store and manage the above basic primitives
c = [1,2,3,'ss'] # a list
d = (1,2,3,'ss') # a tuple
c[0] = 5 # change the first item in the list c, and the index starts from 0.
d[0] = 5 # failed! a tuple is constant, which is the distinguishing property from a list
d={1:22,2:33,4:'ssss','w':123} #a dict: 1, 2, 4 and 'w' are keys of the dict, and 22, 33, 'ssss' and 123 are the corresponding values.
print d[1], d[4], d['w']

# we initialize two objects c and d for storing data at a for loop later
c = list() # an empty list
d = dict() # an empty dict
#test expression
if 1>2:
    print "1 is greater than 2, really?"
else:
    if 2 in [1, 2, 3]: # if 2 is in the list [1, 2, 3]
        #ok, let's start a for loop
        for i in range(5): # equal to for i in [0, 1, 2, 3, 4]
            print i # you can see what's going on in the for loop
            # we append some data to a list c and a dict d
            c.append(math.cos(i)*10 + 2.0**5) # we append the value of 10*cos(i) + 2.0^5 to the list c. We use the math function cos from the module math.
            if i not in d.keys(): # if i is not a key or index of the dict d. 
                d[i] = str(i)

#we can capsule our commands by a function
def GoodJob(input_number, keyword1 = 1, keyword2 = True):
    if keyword2: # that is if keyword2 == True
        print "the input number is", input
    input_number += keyword1 # i.e., the value of input_number is updated to input_number + keyword1
    return input_number # we can return the value
    
# call the function
a = GoodJob(2) # a = 3, with print info 'the input number is 3'
b = GoodJob(3, keyword1 = 5, keyword2 = False) # b = 8, without print info.

Installing SudoDEM

[Binary Installation Package]

Download the latest binary installation package from the SudoDEM project website (https://sudodem.github.io) Download page. Or directly go to SudoDEM’s Github repository (https://github.com/SudoDEM/SudoDEM/releases) to download the compiled binary package.

Extract the binary package to a local directory (such as user directory /home/xxx/), and you will get the following file directory (taking SudoDEM3D as an example):

Through the user configuration file .bashrc (/home/xxx/.bashrc), add the path of the executable file sudodem3d (/home/xxx/SudoDEM/bin) to the environment variable PATH:

PATH=${PATH}:/home/xxx/SudoDEM/bin

Note:

The dot before the file name .bashrc represents a hidden file. In the graphical interface (in the file browsing window), press CTRL+h to show or hide; you can use the built-in gedit editor to edit and modify .bashrc, or use vim to edit and modify directly in the terminal.

[Script Automatic Compilation Installation]

Here is a video that may guide you to compile SudoDEM. You can copy the command lines directly from this video.

Non-root permission compilation and installation is the recommended installation method for SudoDEM. Significantly different from Windows, installing software to the system under Linux will install various parts of the software to corresponding directories of the system. For example, compiled binaries will be installed to the bin directory (such as /bin), dynamic link libraries (in order to compile independent functional modules into separate binary library files for development and other reasons, the main program dynamically calls these library files as needed) will be installed to lib (such as /lib), etc. Installation is simple, but uninstallation may have problems. Installing software to the system with sudo permissions (generally through sudo apt install package) often attaches installation of some dependency libraries (skip if already exists); when uninstalling software, if you choose to uninstall dependency libraries at the same time, it may cause other software to not work properly (the required dependency libraries are uninstalled). Choosing non-root permission installation can have many benefits: avoid the above uninstallation problems, can compile and use specific versions of dependency libraries (not using the system’s), and the system is more lightweight. The latest SudoDEM code provides a one-click compilation installation script (shell script), which can be executed directly in the terminal to automatically download the source code of third-party dependency libraries for compilation and installation. First, download the source code from the SudoDEM code repository, and the file structure is as follows:

Among them, the file INSTALL provides detailed installation instructions, including one-click compilation installation and distributed manual compilation installation. Then, create the third-party dependency library compilation directory 3rdlib, SudoDEM2D and SudoDEM3D compilation directories build2d and build3d (as needed), and the local installation directory of SudoDEM sudodeminstall. The final file directory structure is as follows:

Compilation and installation operations are performed in the scripts directory, which contains the installation scripts as follows:

The first step, install third-party libraries:

./install3rdlibs.sh

If the current system does not have the necessary compilation tools installed, this script will automatically install them and require entering the administrator password. Third-party libraries include Boost, Eigen, libQGLViewer, and Minieigen, shared by both SudoDEM2D and 3D, only need to be compiled and installed once. The second step, install the SudoDEM program (taking SudoDEM3D as an example):

./firstCompile_SudoDEM3D.sh

Note: This script is only used for the first compilation and installation; if you have changed the SudoDEM code, you only need to execute make install in the compilation directory (build2d or build3d) to recompile and install. If you have added cpp files in the SudoDEM source code file directory, you need to re-cmake (i.e., cmake ../SudoDEM3D).