You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+83-6Lines changed: 83 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,11 +8,11 @@ See more info on the webpage:
8
8
9
9
## Easy installation through Anaconda
10
10
11
-
The SSCHA code comes as a python library, with computationally intense part speedup with C, Fortran and Julia. The easiest way to install is through Anaconda ([how to install anaconda](https://www.anaconda.com/download))
11
+
The SSCHA code comes as a python library, with computationally intense part speedup with C, Fortran and Julia. The easiest way to install is through Anaconda ([how to install anaconda](https://www.anaconda.com/download))
@@ -27,7 +27,7 @@ If you want the julia speedup, see the section on Manual installation to preconf
27
27
28
28
## Video lessons from the 2023 School are available
29
29
30
-
The full recordings, both of theoretical lectures, tutorials and Hands-on sessions can be found
30
+
The full recordings, both of theoretical lectures, tutorials and Hands-on sessions can be found
31
31
in our youtube channel [SSCHAcode](https://www.youtube.com/@SSCHAcode>)
32
32
33
33
This is the safest and best way to install the SSCHA. The first line creates a new pristine python environment with all the required libraries to compile the source code. The second line activates the newly installed environment. Then, the thrid command installs the additional dependencies, the last line compiles and install the SSCHA code.
For the development version of the code, subtitute the pip call with the python setup.py install.
177
177
178
+
## Compiling with Meson
179
+
180
+
To compile and install SSCHA with Meson, follow these typical steps:
181
+
182
+
### 1. Change to the Source Directory
183
+
184
+
First, open a terminal and navigate to the root directory of the project source code. This is where the `meson.build` file is located.
185
+
186
+
```bash
187
+
cd /path/to/source/root/python-sscha
188
+
```
189
+
190
+
191
+
### 2. Configure the Build Directory
192
+
193
+
Create and configure a build directory by running:
194
+
195
+
```bash
196
+
meson setup builddir
197
+
```
198
+
199
+
or if you are in a conda env (the best option for a local installation):
200
+
```bash
201
+
meson setup builddir --prefix=$CONDA_PREFIX
202
+
```
203
+
204
+
if you want to use Intel MKL:
205
+
```bash
206
+
setup builddir -Duse_mkl=true
207
+
```
208
+
209
+
This command sets up a separate build directory (`builddir`) where all compiled files and build artifacts will be placed, keeping the source directory clean. After this, change into the build directory:
210
+
211
+
```bash
212
+
cd builddir
213
+
```
214
+
215
+
216
+
### 3. Compile the Project
217
+
218
+
Once inside the build directory, compile the project using:
219
+
220
+
```bash
221
+
meson compile
222
+
```
223
+
224
+
This will compile the source code according to the configuration from the previous step.
225
+
226
+
### 4. Run Tests (Optional)
227
+
228
+
The project includes tests, you need to install pytest to work. You can run them with:
229
+
230
+
```bash
231
+
meson test
232
+
```
233
+
234
+
This step helps verify that the build works correctly.
235
+
236
+
### 5. Install the Project (Optional)
237
+
238
+
To install the compiled binaries, libraries, and other files system-wide (or to a custom location), run:
239
+
240
+
```bash
241
+
meson install
242
+
```
243
+
244
+
or
245
+
246
+
```bash
247
+
sudo meson install
248
+
```
249
+
250
+
You may need superuser privileges (hence `sudo`) to install to system directories.
251
+
252
+
***
253
+
254
+
Following these steps will help you successfully compile, test, and install SSCHA with Meson as their build system.
Note that this specific command may change in time.
79
+
Note that this specific command may change in time.
80
80
81
81
82
82
Together with these mandatory requirements (otherwise, the code will not compile correctly or raise an exception at the startup), we
@@ -90,7 +90,7 @@ If these packages are available, they will enable the automatic cluster/local ca
90
90
To install all the python dependencies (and recommended) automatically, you may just run:
91
91
92
92
.. code-block:: console
93
-
93
+
94
94
pip install -r requirements.txt
95
95
96
96
@@ -102,8 +102,8 @@ Installation from pip
102
102
The easiest way to install python-sscha (and CellConstructor) is through the python package manager:
103
103
104
104
.. code-block:: console
105
-
106
-
pip install python-sscha
105
+
106
+
pip install python-sscha
107
107
108
108
109
109
@@ -116,43 +116,121 @@ Installation from source
116
116
------------------------
117
117
118
118
Once all the dependences of the codes are satisfied, you can unzip the source code downloaded from the website.
119
-
Then run, inside the directory that contains the setup.py script, the following command:
119
+
Then run, inside the directory that contains the meson.build script, the following command:
120
120
121
121
.. code-block:: console
122
122
123
-
python setup.py install
123
+
pip install .
124
124
125
125
126
126
As for the pip installation, you may append the --user option to install the package only for the user (without requiring administrator powers).
127
127
128
+
An "editable" install is highly recommended for developers. It allows you to modify the source code and have the changes reflected immediately without needing to reinstall.
129
+
.. code-block:: console
130
+
131
+
pip install -e .
132
+
128
133
129
134
Install with Intel FORTRAN compiler
130
135
-----------------------------------
131
136
132
-
The setup.py script works automatically with the GNU FORTRAN compiler. However, due to some differences in linking lapack,
133
-
to use the intel compiler you need to edit a bit the setup.py script:
137
+
Meson works automatically with several FORTRAN compilers, including Intel FORTRAN. However, due to some differences in linking lapack,
138
+
to use the intel compiler you need to:
139
+
140
+
Ensure MKL is installed in your Conda environment:
141
+
.. code-block:: console
142
+
143
+
conda install mkl mkl-devel
144
+
145
+
You can pass Meson options through pip's \--config-settings flag.
Meson automatically detects compilers using standard environment variables. You can set these variables before running the installation command. This is the simplest way to specify a compiler for a single build.
161
+
162
+
The key variables are:
163
+
164
+
CC: Specifies the C compiler executable.
143
165
144
-
1. CC (C compiler)
145
-
2. FC (Fortran compiler)
146
-
3. LDSHARED (linking)
166
+
CXX: Specifies the C++ compiler executable.
147
167
148
-
If we want to use a custom compiler in /path/to/fcompiler we may run the setup as:
168
+
FC: Specifies the Fortran compiler executable.
169
+
170
+
Step-by-Step Instructions
171
+
172
+
1. Open your terminal. All commands must be run in the same session, as environment variables are typically not permanent.
173
+
2. Set the environment variables to point to your desired compilers.
A specific setup.py script is provided to install it easily in FOSS clusters.
187
+
.. code-block:: console
188
+
export CXX=/path/to/my/custom/g++
157
189
190
+
3. Combine them as needed. For this project, you will likely need to set CC and FC.
191
+
192
+
# Example using compilers from a specific toolchain
193
+
.. code-block:: console
194
+
export CC=/usr/local/bin/gcc-11
195
+
export FC=/usr/local/bin/gfortran-11
196
+
197
+
4. Run the pip installation. With the variables set, run pip install from the project's root directory. pip will pass the environment variables down to Meson.
198
+
199
+
.. code-block:: console
200
+
# Ensure you are in the project's root directory (where pyproject.toml is)
201
+
pip install .
202
+
203
+
The build process will now use the compilers you specified instead of the system defaults.
204
+
205
+
Method 2: Using a Meson Cross File (Advanced & Reproducible)
For a more permanent or reproducible setup (e.g., in CI/CD pipelines or complex environments), a Meson "cross file" is the best practice. This file explicitly defines the toolchain.
209
+
Step-by-Step Instructions
210
+
211
+
1. Create a cross file. In your project's root directory, create a file named native-toolchain.ini (the name can be anything).
212
+
213
+
2. Edit the file to specify the paths to your compilers in the [binaries] section.
214
+
215
+
Example native-toolchain.ini:
216
+
217
+
.. code-block:: console
218
+
# native-toolchain.ini
219
+
# Defines the compilers to use for the build.
220
+
221
+
[binaries]
222
+
c = '/path/to/my/custom/gcc'
223
+
fortran = '/path/to/my/custom/gfortran'
224
+
225
+
# If you also needed C++, you would add:
226
+
# cpp = '/path/to/my/custom/g++'
227
+
228
+
Note: The keys are c, cpp, and fortran.
229
+
230
+
3. Run the pip installation with meson-args. You can instruct pip to pass configuration settings to meson-python, which in turn passes them to Meson. We use this to specify our cross file.
231
+
232
+
.. code-block:: console
233
+
# The --native-file option tells Meson which toolchain to use.
This method is more explicit and less prone to errors from shell configurations. It ensures that anyone building the project can easily use the exact same toolchain by sharing the native-toolchain.ini file.
0 commit comments