Skip to content

docs: add a Getting Started Section#1577

Merged
polvalente merged 29 commits intoelixir-nx:mainfrom
TomasPegado:docs_refact
Apr 2, 2025
Merged

docs: add a Getting Started Section#1577
polvalente merged 29 commits intoelixir-nx:mainfrom
TomasPegado:docs_refact

Conversation

@TomasPegado
Copy link
Contributor

This pull request looks to enhances the documentation by introducing a "Getting Started" section to help new users quickly understand and begin working with the Nx library in Elixir.

Key Additions:

  • Introduction Page – Provides an overview of Nx, its purpose, and key features.
  • Quickstart Guide – Offers instructions on how to run basic operations, making onboarding smoother for new users.

@@ -0,0 +1,82 @@
# What is Nx?
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@josevalim This is the start of our revamped docs.

We're taking the current getting started guide and both splitting it and getting into more detail.
I'm thinking we should merge these onto a new-docs branch and only merge that onto main after the getting started is fully done.

WDYT?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it is fine to push to main directly, given the plan is for continuous work on it, right?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We'll make it so that this PR is merged when it fully replaces the previous introduction to nx guide.


There are several ways to install Nx (Numerical Elixir), depending on your project type and needs.

## Using Mix in a standardElixir Project
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
## Using Mix in a standardElixir Project
## Using Nx in a Standard Elixir Project


```sh
mix deps.get

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change

```elixir
defp deps do
[
{:nx, github: "elixir-nx/nx", branch: "main"}
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
{:nx, github: "elixir-nx/nx", branch: "main"}
{:nx, github: "elixir-nx/nx", branch: "main", sparse: "nx"}

Comment on lines +60 to +61
IO.inspect(tensor)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
IO.inspect(tensor)
IO.inspect(tensor)


## Installing Nx in a Standalone Script (Without a Mix Project)

If you don’t have a Mix project and just want to run a standalone script, use Mix.install/1 to dynamically fetch and install Nx.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
If you don’t have a Mix project and just want to run a standalone script, use Mix.install/1 to dynamically fetch and install Nx.
If you don’t have a Mix project and just want to run a standalone script, use `Mix.install/1` to dynamically fetch and install Nx.


```sh
elixir my_script.exs

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change


```elixir
Mix.install([
{:nx, github: "elixir-nx/nx", branch: "main"}
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
{:nx, github: "elixir-nx/nx", branch: "main"}
{:nx, github: "elixir-nx/nx", branch: "main", sparse: "nx"}

Comment on lines +123 to +140

Best for: Running Nx on GPUs or TPUs using Google’s XLA compiler.

## Installing Nx with Torchx for PyTorch Acceleration

To run Nx operations on PyTorch’s backend (LibTorch):

1. Modify mix.exs:

```elixir
defp deps do
[
{:nx, "~> 0.5"},
{:torchx, "~> 0.5"} # PyTorch Backend
]
end

```
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Best for: Running Nx on GPUs or TPUs using Google’s XLA compiler.
## Installing Nx with Torchx for PyTorch Acceleration
To run Nx operations on PyTorch’s backend (LibTorch):
1. Modify mix.exs:
```elixir
defp deps do
[
{:nx, "~> 0.5"},
{:torchx, "~> 0.5"} # PyTorch Backend
]
end
```

Let's not mention Torchx. We could maybe reference EMLX, but it's not even released yet, so let's leave this for later.

Comment on lines +141 to +186

2. Fetch dependencies:

```sh
mix deps.get
```

3. Run with EXLA enabled:

```elixir
Torchx.set_preferred_backend()
```

Best for: Deep learning applications with PyTorch acceleration.

## Installing Nx with OpenBLAS for CPU Optimization

To optimize CPU performance with OpenBLAS:

1. Install OpenBLAS (libopenblas):
- Ubuntu/Debian:
```sh
sudo apt install libopenblas-dev
```
- MacOS (using Homebrew):
```sh
brew install openblas
```
2. Modify mix.exs:

```elixir
defp deps do
[
{:nx, "~> 0.5"},
{:openblas, "~> 0.5"} # CPU-optimized BLAS backend
]
end
```

3. Fetch dependencies:

```sh
mix deps.get
```

Best for: Optimizing CPU-based tensor computations.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
2. Fetch dependencies:
```sh
mix deps.get
```
3. Run with EXLA enabled:
```elixir
Torchx.set_preferred_backend()
```
Best for: Deep learning applications with PyTorch acceleration.
## Installing Nx with OpenBLAS for CPU Optimization
To optimize CPU performance with OpenBLAS:
1. Install OpenBLAS (libopenblas):
- Ubuntu/Debian:
```sh
sudo apt install libopenblas-dev
```
- MacOS (using Homebrew):
```sh
brew install openblas
```
2. Modify mix.exs:
```elixir
defp deps do
[
{:nx, "~> 0.5"},
{:openblas, "~> 0.5"} # CPU-optimized BLAS backend
]
end
```
3. Fetch dependencies:
```sh
mix deps.get
```
Best for: Optimizing CPU-based tensor computations.

Comment on lines +106 to +126
deftransform compute_tensor_from_list(list) do
tensor = Nx.tensor(list)
double_tensor(tensor)
end
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's add an example that does shape validation and manipulation, such as adding a new axis and changing things around

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On it!

@TomasPegado TomasPegado force-pushed the docs_refact branch 2 times, most recently from d006d3d to e58062b Compare March 29, 2025 21:09
pejrich and others added 20 commits March 31, 2025 17:06
Co-authored-by: José Valim <jose.valim@dashbit.co>
…ir-nx#1582)

Co-authored-by: Paulo Valente <16843419+polvalente@users.noreply.github.com>
Co-authored-by: Paulo Valente <16843419+polvalente@users.noreply.github.com>
Co-authored-by: José Valim <jose.valim@dashbit.co>
Copy link
Contributor

@polvalente polvalente left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Congrats! The new documentation covers quite a bit more surface area, and will probably allow for more growth in the future!

@polvalente polvalente merged commit f9428e6 into elixir-nx:main Apr 2, 2025
7 of 8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants