Skip to content

Commit cb7894e

Browse files
jimmytweijimmytwei
authored
Update README.md
1 parent 3247df8 commit cb7894e

File tree

1 file changed

+124
-83
lines changed
  • AI-and-Analytics/Getting-Started-Samples/Modin_GettingStarted

1 file changed

+124
-83
lines changed

‎AI-and-Analytics/Getting-Started-Samples/Modin_GettingStarted/README.md

Lines changed: 124 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
# Modin* Get Started Sample
22

3-
The `Modin* Getting Started` sample demonstrates how to use distributed Pandas using the Modin package.
3+
The `Modin Getting Started` sample demonstrates how to use distributed Pandas using the Modin package.
44

55
| Area | Description
66
| :--- | :---
77
| Category | Getting Started
8-
| What you will learn | Basic Modin* programming model for Intel processors
8+
| What you will learn | Basic Modin programming model for Intel processors
99
| Time to complete | 5 to 8 minutes
1010

1111
## Purpose
@@ -20,92 +20,131 @@ In this sample, you will run Modin-accelerated Pandas functions and note the per
2020
| :--- | :---
2121
| OS | Ubuntu* 18.04 (or newer)
2222
| Hardware | Intel® Atom® processors <br> Intel® Core™ processor family <br> Intel® Xeon® processor family <br> Intel® Xeon® Scalable Performance processor family
23-
| Software | Modin
23+
| Software | Modin
24+
> **Note**: AI and Analytics samples are validated on AI Tools Offline Installer. For the full list of validated platforms refer to [Platform Validation](https://github.com/oneapi-src/oneAPI-samples/tree/master?tab=readme-ov-file#platform-validation).
2425
2526
## Key Implementation Details
2627

2728
This get started sample code is implemented for CPU using the Python language. The example assumes you have Pandas and Modin installed inside a conda environment.
2829

2930
## Environment Setup
31+
You will need to download and install the following toolkits, tools, and components to use the sample.
32+
33+
**1. Get AI Tools**
34+
35+
Required AI Tools: Modin
36+
37+
If you have not already, select and install these Tools via [AI Tools Selector](https://www.intel.com/content/www/us/en/developer/tools/oneapi/ai-tools-selector.html). AI and Analytics samples are validated on AI Tools Offline Installer. It is recommended to select Offline Installer option in AI Tools Selector.
38+
39+
>**Note**: If Docker option is chosen in AI Tools Selector, refer to [Working with Preset Containers](https://github.com/intel/ai-containers/tree/main/preset) to learn how to run the docker and samples.
40+
41+
**2. (Offline Installer) Activate the AI Tools bundle base environment**
42+
<!-- this step is from AI Tools GSG, please don't modify unless GSG is updated -->
43+
If the default path is used during the installation of AI Tools:
44+
```
45+
source $HOME/intel/oneapi/intelpython/bin/activate
46+
```
47+
If a non-default path is used:
48+
```
49+
source <custom_path>/bin/activate
50+
```
51+
52+
**3. (Offline Installer) Activate relevant Conda environment**
53+
<!-- specify relevant conda environment name in Offline Installer for this sample -->
54+
```
55+
conda activate modin
56+
```
57+
58+
**4. Clone the GitHub repository**
59+
<!-- for oneapi-samples: git clone https://github.com/oneapi-src/oneAPI-samples.git
60+
cd oneAPI-samples/AI-and-Analytics/<samples-folder>/<individual-sample-folder> -->
61+
```
62+
git clone https://github.com/oneapi-src/oneAPI-samples.git
63+
cd oneAPI-samples/AI-and-Analytics/Getting-Started-Samples/Modin_GettingStarted
64+
```
65+
66+
**5. Install dependencies**
67+
<!-- It is required to have requirement.txt file in sample dir. It should list additional libraries, such as matplotlib, ipykernel etc. -->
68+
>**Note**: Before running the following commands, make sure your Conda/Python environment with AI Tools installed is activated
69+
70+
```
71+
pip install -r requirements.txt
72+
pip install notebook
73+
```
74+
For Jupyter Notebook, refer to [Installing Jupyter](https://jupyter.org/install) for detailed installation instructions.
75+
76+
## Run the Sample
77+
>**Note**: Before running the sample, make sure [Environment Setup](https://github.com/oneapi-src/oneAPI-samples/tree/master/AI-and-Analytics/Getting-Started-Samples/INC-Quantization-Sample-for-PyTorch#environment-setup) is completed.
78+
79+
Go to the section which corresponds to the installation method chosen in [AI Tools Selector](https://www.intel.com/content/www/us/en/developer/tools/oneapi/ai-tools-selector.html) to see relevant instructions:
80+
* [AI Tools Offline Installer (Validated)](#ai-tools-offline-installer-validated)
81+
* [Conda/PIP](#condapip)
82+
* [Docker](#docker)
83+
84+
85+
### AI Tools Offline Installer (Validated)
86+
87+
**1. Register Conda kernel to Jupyter Notebook kernel**
88+
89+
If the default path is used during the installation of AI Tools:
90+
```
91+
$HOME/intel/oneapi/intelpython/envs/modin/bin/python -m ipykernel install --user --name=modin
92+
```
93+
If a non-default path is used:
94+
```
95+
<custom_path>/bin/python -m ipykernel install --user --name=modin
96+
```
97+
**2. Launch Jupyter Notebook**
98+
<!-- add other flags to jupyter notebook command if needed, such as port 8888 or allow-root -->
99+
```
100+
jupyter notebook --ip=0.0.0.0
101+
```
102+
**3. Follow the instructions to open the URL with the token in your browser**
103+
104+
**4. Select the Notebook**
105+
<!-- add sample file name -->
106+
```
107+
Modin_GettingStarted.ipynb
108+
```
109+
**5. Change the kernel to `modin`**
110+
<!-- specify relevant kernel name(s), for example `pytorch` -->
111+
**6. Run every cell in the Notebook in sequence**
112+
113+
### Conda/PIP
114+
> **Note**: Before running the instructions below, make sure your Conda/Python environment with AI Tools installed is activated
115+
116+
**1. Register Conda/Python kernel to Jupyter Notebook kernel**
117+
<!-- keep placeholders in this step, user could use any name for Conda/PIP env -->
118+
For Conda:
119+
```
120+
<CONDA_PATH_TO_ENV>/bin/python -m ipykernel install --user --name=<your-env-name>
121+
```
122+
To know <CONDA_PATH_TO_ENV>, run `conda env list` and find your Conda environment path.
123+
124+
For PIP:
125+
```
126+
python -m ipykernel install --user --name=<your-env-name>
127+
```
128+
**2. Launch Jupyter Notebook**
129+
<!-- add other flags to jupyter notebook command if needed, such as port 8888 or allow-root -->
130+
```
131+
jupyter notebook --ip=0.0.0.0
132+
```
133+
**3. Follow the instructions to open the URL with the token in your browser**
134+
135+
**4. Select the Notebook**
136+
<!-- add sample file name -->
137+
```
138+
Modin_GettingStarted.ipynb
139+
```
140+
**5. Change the kernel to `<your-env-name>`**
141+
<!-- leave <your-env-name> as a placeholder as user could choose any name for the env -->
142+
143+
**6. Run every cell in the Notebook in sequence**
144+
145+
### Docker
146+
AI Tools Docker images already have Get Started samples pre-installed. Refer to [Working with Preset Containers](https://github.com/intel/ai-containers/tree/main/preset) to learn how to run the docker and samples.
30147

31-
1. Install Modin in a new conda environment.
32-
33-
>**Note:** replace python=3.x with your own Python version
34-
```
35-
conda create -n modin python=3.x -y
36-
conda activate modin
37-
conda install modin-all -c conda-forge -y
38-
```
39-
40-
2. Install Matplotlib.
41-
```
42-
conda install -c conda-forge matplotlib -y
43-
```
44-
45-
3. Install Jupyter Notebook.
46-
```
47-
conda install jupyter nb_conda_kernels -y
48-
```
49-
50-
4. Create a new kernel for Jupyter Notebook based on your activated conda environment. (This step is optional if you plan to open the Notebook on your local server.)
51-
```
52-
conda install ipykernel
53-
python -m ipykernel install --user --name usr_modin
54-
```
55-
## Run the `Modin* Get Started` Sample
56-
57-
You can run the Jupyter notebook with the sample code on your local server or download the sample code from the notebook as a Python file and run it locally.
58-
59-
### Run the Sample in Visual Studio Code* (Optional)
60-
61-
You can use Visual Studio Code (VS Code) extensions to set your environment, create launch configurations, and browse and download samples.
62-
63-
The basic steps to build and run a sample using VS Code include:
64-
65-
1. Download a sample using the extension **Code Sample Browser for Intel Software Developer Tools**.
66-
2. Configure the oneAPI environment with the extension **Environment Configurator for Intel Software Developer Tools**.
67-
3. Open a Terminal in VS Code by clicking **Terminal** > **New Terminal**.
68-
4. Run the sample in the VS Code terminal using the instructions below.
69-
70-
On Linux, you can debug your GPU application with GDB for Intel® oneAPI toolkits using the **Generate Launch Configurations** extension.
71-
72-
To learn more about the extensions, see
73-
[Using Visual Studio Code with Intel® oneAPI Toolkits](https://software.intel.com/content/www/us/en/develop/documentation/using-vs-code-with-intel-oneapi/top.html).
74-
75-
76-
### In Jupyter Notebook
77-
78-
1. Activate the conda environment.
79-
```
80-
conda activate aikit-modin
81-
```
82-
83-
2. Start the Jupyter Notebook server.
84-
```
85-
jupyter notebook
86-
```
87-
88-
3. Locate and open the Notebook.
89-
```
90-
Modin_GettingStarted.ipynb
91-
```
92-
93-
4. Click the **Run** button to move through the cells in sequence.
94-
95-
### Run the Python Script Locally
96-
97-
1. Convert ``Modin_GettingStarted.ipynb`` to a Python file. There are two options.
98-
99-
1. Open the notebook and download the script as Python file: **File > Download as > Python (py)**.
100-
101-
2. Convert the notebook file to a Python script using commands similar to the following.
102-
```
103-
jupyter nbconvert --to python Modin_GettingStarted.ipynb
104-
```
105-
2. Run the Python script.
106-
```
107-
ipython Modin_GettingStarted.py
108-
```
109148

110149
### Expected Output
111150

@@ -118,8 +157,10 @@ The expected cell output is shown in the `Modin_GettingStarted.ipynb` Notebook.
118157
## License
119158

120159
Code samples are licensed under the MIT license. See
121-
[License.txt](https://github.com/oneapi-src/oneAPI-samples/blob/master/License.txt) for details.
160+
[License.txt](https://github.com/oneapi-src/oneAPI-samples/blob/master/License.txt)
161+
for details.
122162

123-
Third party program Licenses can be found here: [third-party-programs.txt](https://github.com/oneapi-src/oneAPI-samples/blob/master/third-party-programs.txt).
163+
Third party program Licenses can be found here:
164+
[third-party-programs.txt](https://github.com/oneapi-src/oneAPI-samples/blob/master/third-party-programs.txt)
124165

125166
*Other names and brands may be claimed as the property of others. [Trademarks](https://www.intel.com/content/www/us/en/legal/trademarks.html)

0 commit comments

Comments
 (0)