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.

Sign up for GitHub

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

[Doc] Update global settings #6201

Merged
merged 5 commits into from
Sep 30, 2022
Merged

[Doc] Update global settings #6201

Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
cf601ba
[Doc] Update global settings
Olinaaaloompa Sep 29, 2022
0caa032
Apply suggestions from code review
Olinaaaloompa Sep 29, 2022
2185d46
Apply suggestions from code review
Olinaaaloompa Sep 30, 2022
90b92b4
Update docs/lang/articles/reference/global_settings.md
Olinaaaloompa Sep 30, 2022
4d84493
Update docs/lang/articles/reference/global_settings.md
Olinaaaloompa Sep 30, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 29 additions & 31 deletions docs/lang/articles/reference/global_settings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,19 +4,17 @@ sidebar_position: 3

# Global Settings

Every Taichi program starts with `ti.init()`. You can customize your Taichi runtime by passing arguments to `ti.init()` or setting environment variables. Each argument or environment variable controls one specific behavior of the Taichi runtime. For example, the argument `arch` specifies the backend, and the argument `debug` decides whether to run the program in debug mode.

The call `ti.init()` is indispensable in every Taichi program. Taichi allows you to customize your Taichi runtime by passing arguments to `ti.init()` or setting environment variables. Each argument or environment variable controls one specific behavior of the Taichi runtime. For example, the argument `arch` specifies the backend, and the argument `debug` decides whether to run the program in debug mode. The document [Hello, World!](../get-started/index.md) gives a brief introduction to this function, and this document provides more details.
Taichi executes the following to initialize a specific configuration in the `ti.init()` method call. Taking the `arch` argument as an example:

Generally, when you call `ti.init()`, Taichi executes the following steps to initialize a specific configuration. We use the `arch` argument as an example:

1. Taichi looks for the arguments passed to `ti.init()`. In this case, after Taichi reads `ti.init(arch=cuda)`, it chooses CUDA as the backend and omits the environment variable.
2. If no argument is found, Taichi checks the corresponding environment variable. In this case, if `arch` is not specified but the environment variable is set to `export TI_ARCH=cuda`, Taichi chooses CUDA as the backend.
1. Taichi first looks for the arguments passed to `ti.init()`. In this case, after Taichi reads `ti.init(arch=cuda)`, it chooses CUDA as the backend and ignores the corresponding environment variable for backend setting, namely, `TI_ARCH`.
2. If no argument is found, Taichi checks the corresponding environment variable. In this case, if `arch` is not specified but the environment variable is set to `export TI_ARCH=cuda`, Taichi still chooses CUDA as the backend.
3. If no customized setting is found, Taichi uses a default configuration. In this case, if neither the argument `arch` is specified nor an environment variable `TI_ARCH` is found, Taichi adopts the default backend `arch=ti.cpu`.

Following are some frequently-used configurations in `ti.init()`:

Following are some frequently used configurations that the `ti.init()` method call supports:

**Customize `ti.init()` via arguments**
**Customize Taichi runtime via arguments**

```
[Backend Options]
Expand All @@ -31,13 +29,13 @@ Following are some frequently used configurations that the `ti.init()` method ca
[Compilation Options]

advanced_optimization: bool
Enable/disable advanced optimization to save compile time and reduce possible errors.
Enable/disable advanced optimization. Turning off the setting can save compile time and reduce possible errors.

fast_math: bool
Enable/disable fast math to prevent possible undefined math behavior.
Enable/disable fast math. Turning off the setting can prevent possible undefined math behavior.

print_ir: bool
Turn on/off printing intermediate IR generated.
Turn on/off the printing of the intermediate IR generated.


[Runtime Options]
Expand All @@ -46,7 +44,7 @@ Following are some frequently used configurations that the `ti.init()` method ca
Set the number of threads used by the CPU thread pool.

debug: bool
Run program in debug mode.
Run your program in debug mode.

default_cpu_block_dim: int
Set the number of threads in a block on CPU.
Expand All @@ -61,7 +59,7 @@ Following are some frequently used configurations that the `ti.init()` method ca
Set the default precision of integers in the Taichi scope.

dynamic_index: bool
Enable/disable the use of variables as indices to access vector/matrix elements in the Taichi scope.
Enable/disable the use of variables as indices when accessing vector/matrix elements in the Taichi scope.

kernel_profiler: bool
Turn on/off kernel performance profiling.
Expand All @@ -85,19 +83,19 @@ Following are some frequently used configurations that the `ti.init()` method ca
Set the logging level.

verbose: bool
Turn on/off verbose outputs. For example, set `ti.init(verbose=False)` to eliminate verbose outputs.
Turn on/off verbose outputs. For example, `ti.init(verbose=False)` prevents verbose outputs.


[Develop Options]

gdb_trigger: bool
Enable/disable triggering GDB when Taichi crashes, e.g. `ti.init(gdb_trigger=True)`.
Enable/disable GDB when Taichi crashes. For example, `ti.init(gdb_trigger=True)` activates GDB.
Olinaaaloompa marked this conversation as resolved.
Show resolved Hide resolved
Olinaaaloompa marked this conversation as resolved.
Show resolved Hide resolved
```


**Customize `ti.init()` via environment variables**
**Customize Taichi runtime via environment variables**

Below are some environment variables that you can set to customize your Taichi program, they overlap but are not in one-to-one correspondence with the `ti.init()` arguments listed above:
Taichi allows a number of environment variables for runtime customization. Some provide an alternative to the `ti.init()` arguments listed above. For example, as mentioned above, `arch` is interchangeable with `TI_ARCH`. But not all of the environment variables can be replaced by arguments, and vice versa.

```
[Backend Options]
Expand All @@ -118,7 +116,7 @@ Below are some environment variables that you can set to customize your Taichi p
[Runtime Options]

TI_DEBUG
Turn on/off the debug mode. For example, `export TI_DEBUG=1` activates the debug mode.
Turn on/off debug mode. For example, `export TI_DEBUG=1` activates debug mode.

TI_ENABLE_TORCH
Enable/disable the import of torch upon startup. For example, `export TI_ENABLE_TORCH=0` prohibits the use of torch.
Expand All @@ -132,7 +130,8 @@ Below are some environment variables that you can set to customize your Taichi p
[Develop Options]

TI_CACHE_RUNTIME_BITCODE
Enable/disable the caching of compiled runtime bitcode in developer mode to save startup time. For example, `export TI_CACHE_RUNTIME_BITCODE=1` enables the program to cache compiled runtime bitcode.
Enable/disable the caching of compiled runtime bitcode in developer mode. For example, `export TI_CACHE_RUNTIME_BITCODE=1` enables the program to cache compiled runtime bitcode.
Turning off the setting can save startup time.

TI_TEST_THREADS
Specify the number of threads to run a test. For example, set `export TI_TEST_THREADS=4` to allocate four threads.
Expand All @@ -142,28 +141,28 @@ Below are some environment variables that you can set to customize your Taichi p
[Logging Options]

TI_LOG_LEVEL
Set the logging level, such as `export TI_LOG_LEVEL=trace`.
Set the logging level. For example, `export TI_LOG_LEVEL=trace` enables the TRACE level.
```

## Backends

- To specify which architecture to use: `ti.init(arch=ti.cuda)`. This argument is equivalent to the environment variable `TI_ARCH`.
- To specify the pre-allocated memory size for CUDA: For example, `ti.init(device_memory_GB=0.5)` allocates 0.5 GB size of memory.
- To specify which architecture to use: `ti.init(arch=ti.cuda)` designates CUDA as the backend. This argument is equivalent to the environment variable `TI_ARCH`.
- To specify the pre-allocated memory size for CUDA: `ti.init(device_memory_GB=0.5)` allocates 0.5 GB size of memory.
- To specify which GPU to use for CUDA: `export CUDA_VISIBLE_DEVICES=[gpuid]`.
- To specify which GPU to use for VULKAN: `export TI_VISIBLE_DEVICE=[gpuid]`.
- To disable a backend (`CUDA`, `METAL`, `OPENGL`) upon startup: For example, `export TI_ENABLE_CUDA=0` disables CUDA.
- To disable a backend (`CUDA`, `METAL`, `OPENGL`) upon startup: `export TI_ENABLE_CUDA=0` disables CUDA.
Olinaaaloompa marked this conversation as resolved.
Show resolved Hide resolved
Olinaaaloompa marked this conversation as resolved.
Show resolved Hide resolved

:::note

If you want to use CUDA and Taichi's GGUI system at the same time on a machine with multiple GPU cards, ensure that `CUDA_VISIBLE_DEVICES` matches `TI_VISIBLE_DEVICE`. In principle, `CUDA_VISIBLE_DEVICES` and `TI_VISIBLE_DEVICE` should point to a GPU device with the same UUID. Use `nvidia-smi -L` to retrieve the details of your GPU devices.
If you want to use CUDA and Taichi's GGUI system at the same time on a machine with multiple GPU cards, ensure that `CUDA_VISIBLE_DEVICES` matches `TI_VISIBLE_DEVICE`. In principle, `CUDA_VISIBLE_DEVICES` and `TI_VISIBLE_DEVICE` should point to the same GPU device identified with UUID. Use `nvidia-smi -L` to retrieve the details of your GPU devices.

:::

## Compilation

- To disable advanced optimization to save compile time and reduce possible errors: `ti.init(advanced_optimization=False)`.
- To disable fast math to prevent possible undefined math behavior: `ti.init(fast_math=False)`.
- To print intermediate IR generated: `ti.init(print_ir=True)`. Note that compiled kernels are [cached by default](../performance_tuning/performance.md#offline-cache). To force compilation and IR emission, use `ti.init(print_ir=True, offline_cache=False)`.
- To disable advanced optimization: `ti.init(advanced_optimization=False)`, which helps save compile time and reduce possible errors.
- To disable fast math: `ti.init(fast_math=False)`, which helps prevent possible undefined math behavior.
- To print the intermediate IR generated: `ti.init(print_ir=True)`. Note that compiled kernels are [cached by default](../performance_tuning/performance.md#offline-cache). To force compilation and IR emission, use `ti.init(print_ir=True, offline_cache=False)`.


## Runtime
Expand All @@ -183,20 +182,19 @@ If you want to use CUDA and Taichi's GGUI system at the same time on a machine w

## Logging

- To set the logging level: For example, set `ti.init(log_level=ti.TRACE)` or `ti.set_logging_level(ti.TRACE)` to choose TRACE. The environment variable `TI_LOG_LEVEL` serves the same purpose.
- To set the logging level: `ti.init(log_level=ti.TRACE)` or `ti.set_logging_level(ti.TRACE)` enables the TRACE level. The environment variable `TI_LOG_LEVEL` serves the same purpose.
- To eliminate verbose outputs: `ti.init(verbose=False)`.

## Develop

- To trigger GDB when Taichi crashes: `ti.init(gdb_trigger=True)`.
- To cache compiled runtime bitcode in **dev mode** to save startup time: `export TI_CACHE_RUNTIME_BITCODE=1`.
- To cache compiled runtime bitcode in **dev mode**: `export TI_CACHE_RUNTIME_BITCODE=1`, which saves startup time.
- To allocate four threads to run a test: `export TI_TEST_THREADS=4` or `python tests/run_tests.py -t4`.


:::note

If `ti.init` is called twice, then the configuration in first invocation
will be completely discarded, e.g.:
If `ti.init` is called twice, the configuration in the first call is discarded. For example:

```python {1,3}
ti.init(debug=True)
Expand Down