Skip to content

Commit a22ccda

Browse files
SCiarellaSCiarella
authored
Enhance install instructions (#75)
* Enhance install instructions
1 parent 9586fa5 commit a22ccda

File tree

2 files changed

+167
-40
lines changed

2 files changed

+167
-40
lines changed

‎README.md‎

Lines changed: 62 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -33,25 +33,68 @@ This repository contains the workflow to implement and train machine learning mo
3333

3434
To get started with the project, follow these steps:
3535

36-
- **Prerequisites:**
37-
In order to correctly install `speckcn2` you need `python3.9` or higher. If you don't have it installed, you can download it from the [official website](https://www.python.org/downloads/). You will also need the header files that are required to compile Python extensions and are contained in `python3-dev`. On Ubuntu, you can install them with:
38-
```bash
39-
apt-get install python3-dev
40-
```
41-
42-
- **Install the package:**
43-
```bash
44-
python -m pip install speckcn2
45-
```
46-
47-
- **Or: Clone the repository:**
48-
```bash
49-
git clone https://github.com/MALES-project/SpeckleCn2Profiler.git
50-
cd SpeckleCn2Profiler
51-
git submodule init
52-
git submodule update
53-
pip install .
54-
```
36+
### Prerequisites
37+
38+
To correctly install `speckcn2`, you need **Python 3.9 or higher**. If you don't have it installed, you can download it from the [official website](https://www.python.org/downloads/).
39+
40+
You will also need header files required to compile Python extensions (contained in `python3-dev`):
41+
42+
**Ubuntu/Debian:**
43+
```bash
44+
sudo apt-get install python3-dev
45+
```
46+
47+
**Other systems:**
48+
```bash
49+
# Fedora/RHEL
50+
sudo dnf install python3-devel
51+
52+
# macOS
53+
xcode-select --install
54+
55+
# Windows: Headers are included with the official Python installer
56+
```
57+
58+
### Installation
59+
60+
#### Option 1: Install from PyPI (Recommended)
61+
62+
```bash
63+
python -m pip install speckcn2
64+
```
65+
66+
We **strongly recommend** using a virtual environment:
67+
68+
```bash
69+
# Create virtual environment
70+
python -m venv speckcn2-env
71+
72+
# Activate virtual environment
73+
# On Linux/macOS:
74+
source speckcn2-env/bin/activate
75+
# On Windows:
76+
# speckcn2-env\Scripts\activate
77+
78+
# Install the package
79+
python -m pip install speckcn2
80+
```
81+
82+
**Verify installation:**
83+
```bash
84+
python -c "import speckcn2; print('Installation successful!')"
85+
```
86+
87+
#### Option 2: Development Installation
88+
89+
For advanced users and developers who want to modify the code:
90+
91+
```bash
92+
git clone https://github.com/MALES-project/SpeckleCn2Profiler.git
93+
cd SpeckleCn2Profiler
94+
git submodule init
95+
git submodule update
96+
pip install -e .
97+
```
5598

5699
## Usage
57100

‎docs/installation.md‎

Lines changed: 105 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,116 @@
11
# Installation
2-
To get started with the project, follow these steps:
32

4-
- **Prerequisites:**
5-
In order to correctly install `speckcn2` you need `python3.9` or higher. If you don't have it installed, you can download it from the [official website](https://www.python.org/downloads/). You will also need the Python header files that are required to compile extensions. On Ubuntu, you can install them with:
6-
```bash
7-
apt-get install python3-dev
8-
```
3+
This guide provides step-by-step instructions for installing `speckcn2` on different platforms and setups.
94

10-
- **Install the package:**
11-
```bash
12-
python -m pip install speckcn2
13-
```
5+
## Prerequisites
146

15-
- **Or: Clone the repository:**
16-
```bash
17-
git clone https://github.com/MALES-project/SpeckleCn2Profiler.git
18-
cd SpeckleCn2Profiler
19-
git submodule init
20-
git submodule update
21-
```
7+
To correctly install `speckcn2`, you need **Python 3.9 or higher**. If you don't have it installed, you can download it from the [official Python website](https://www.python.org/downloads/).
228

23-
## MacOS M1 arm64
9+
You will also need header files required to compile Python extensions (contained in `python3-dev`):
2410

25-
Some dependencies (e.g. `scikit`) do not support the latest python version (3.12). Also `py3nj`, a dependency of `escnn`, requires openmp. We've installed this via homebrew and thus explicitly specifying the C compiler (gnu) prior to installation of this package does the trick.
11+
=== "Ubuntu/Debian"
12+
```bash
13+
sudo apt-get install python3-dev
14+
```
2615

27-
```sh
16+
=== "Fedora/RHEL"
17+
```bash
18+
sudo dnf install python3-devel
19+
```
20+
21+
=== "macOS"
22+
```bash
23+
xcode-select --install
24+
```
25+
26+
=== "Windows"
27+
Headers are included with the official Python installer - no additional steps needed.
28+
29+
## Installation Options
30+
31+
### Option 1: Install from PyPI (Recommended)
32+
33+
This is the simplest way to install `speckcn2` for regular usage:
34+
35+
```bash
36+
python -m pip install speckcn2
37+
```
38+
39+
#### Using Virtual Environment (Strongly Recommended)
40+
41+
We **strongly recommend** using a virtual environment to avoid dependency conflicts:
42+
43+
=== "Linux/macOS"
44+
```bash
45+
# Create virtual environment
46+
python -m venv speckcn2-env
47+
48+
# Activate virtual environment
49+
source speckcn2-env/bin/activate
50+
51+
# Install the package
52+
python -m pip install speckcn2
53+
```
54+
55+
=== "Windows"
56+
```cmd
57+
# Create virtual environment
58+
python -m venv speckcn2-env
59+
60+
# Activate virtual environment
61+
speckcn2-env\Scripts\activate
62+
63+
# Install the package
64+
python -m pip install speckcn2
65+
```
66+
67+
#### Verify Installation
68+
69+
After installation, verify that everything works correctly:
70+
71+
```bash
72+
python -c "import speckcn2; print('Installation successful!')"
73+
```
74+
75+
### Option 2: Development Installation
76+
77+
For advanced users and developers who want to modify the code or contribute to the project:
78+
79+
```bash
80+
git clone https://github.com/MALES-project/SpeckleCn2Profiler.git
81+
cd SpeckleCn2Profiler
82+
git submodule init
83+
git submodule update
84+
pip install -e .
85+
```
86+
87+
The `-e` flag installs the package in "editable" mode, meaning changes to the source code will be immediately reflected without reinstalling.
88+
89+
## Platform-Specific Instructions
90+
91+
### macOS with Apple Silicon (M1/M2)
92+
93+
Apple Silicon Macs require special handling due to dependency compatibility issues:
94+
95+
!!! warning "Python Version Limitation"
96+
Some dependencies (e.g., `scikit-learn`) may not support the latest Python version (3.12). We recommend using Python 3.10 or 3.11.
97+
98+
The `py3nj` dependency of `escnn` requires OpenMP, which needs to be installed via Homebrew with explicit compiler specification:
99+
100+
```bash
101+
# Create conda environment with compatible Python version
28102
conda create -n speckcn2 python=3.10
29103
conda activate speckcn2
30-
CC=gcc-13 pip3 install py3nj # install py3nj before with gcc instead of clang
104+
105+
# Install py3nj with GNU compiler (instead of clang)
106+
CC=gcc-13 pip install py3nj
107+
108+
# Install speckcn2
31109
pip install -e .
32110
```
111+
112+
!!! tip "Installing GCC"
113+
If you don't have `gcc-13` installed, you can install it via Homebrew:
114+
```bash
115+
brew install gcc
116+
```

0 commit comments

Comments
 (0)