Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add a Getting Started Section #1577

Open
wants to merge 4 commits into
base: main
Choose a base branch
from

Conversation

TomasPegado
Copy link

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
Collaborator

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.

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.

3 participants