gstaichi.lang.misc#

Attributes#

`i`	Axis 0. For multi-dimensional arrays it's the direction downward the rows.
`j`	Axis 1. For multi-dimensional arrays it's the direction across the columns.
`k`	Axis 2. For arrays of dimension d >= 3, view each cell as an array of
`l`	Axis 3. For arrays of dimension d >= 4, view each cell as an array of
`ij`	Axes (0, 1).
`ik`	Axes (0, 2).
`il`	Axes (0, 3).
`jk`	Axes (1, 2).
`jl`	Axes (1, 3).
`kl`	Axes (2, 3).
`ijk`	Axes (0, 1, 2).
`ijl`	Axes (0, 1, 3).
`ikl`	Axes (0, 2, 3).
`jkl`	Axes (1, 2, 3).
`ijkl`	Axes (0, 1, 2, 3).
`x86_64`	The x64 CPU backend.
`x64`	The X64 CPU backend.
`arm64`	The ARM CPU backend.
`cuda`	The CUDA backend.
`amdgpu`	The AMDGPU backend.
`metal`	The Apple Metal backend.
`vulkan`	The Vulkan backend.
`gpu`	A list of GPU backends supported on the current system.
`cpu`	A list of CPU backends supported on the current system.
`extension`	An instance of GsTaichi extension.

Functions#

`reset`()	Resets GsTaichi to its initial state.
`init`([arch, default_fp, default_ip, _test_mode, ...])	Initializes the GsTaichi runtime.
`no_activate`(*args)	Deactivates a SNode pointer.
`block_local`(*args)	Hints GsTaichi to cache the fields and to enable the BLS optimization.
`mesh_local`(*args)	Hints the compiler to cache the mesh attributes
`cache_read_only`(*args)
`assume_in_range`(val, base, low, high)	Hints the compiler that a value is between a specified range,
`loop_config`(*[, block_dim, serialize, parallelize, ...])	Sets directives for the next loop
`global_thread_idx`()	Returns the global thread id of this running thread,
`mesh_patch_idx`()	Returns the internal mesh patch id of this running thread,

Module Contents#

gstaichi.lang.misc.i[source]#: Axis 0. For multi-dimensional arrays it’s the direction downward the rows. For a 1d array it’s the direction along this array.

gstaichi.lang.misc.j[source]#: Axis 1. For multi-dimensional arrays it’s the direction across the columns.

gstaichi.lang.misc.k[source]#: Axis 2. For arrays of dimension d >= 3, view each cell as an array of lower dimension d-2, it’s the first axis of this cell.

gstaichi.lang.misc.l[source]#: Axis 3. For arrays of dimension d >= 4, view each cell as an array of lower dimension d-2, it’s the second axis of this cell.

gstaichi.lang.misc.ij[source]#: Axes (0, 1).

gstaichi.lang.misc.ik[source]#: Axes (0, 2).

gstaichi.lang.misc.il[source]#: Axes (0, 3).

gstaichi.lang.misc.jk[source]#: Axes (1, 2).

gstaichi.lang.misc.jl[source]#: Axes (1, 3).

gstaichi.lang.misc.kl[source]#: Axes (2, 3).

gstaichi.lang.misc.ijk[source]#: Axes (0, 1, 2).

gstaichi.lang.misc.ijl[source]#: Axes (0, 1, 3).

gstaichi.lang.misc.ikl[source]#: Axes (0, 2, 3).

gstaichi.lang.misc.jkl[source]#: Axes (1, 2, 3).

gstaichi.lang.misc.ijkl[source]#: Axes (0, 1, 2, 3).

gstaichi.lang.misc.x86_64[source]#: The x64 CPU backend.

gstaichi.lang.misc.x64[source]#: The X64 CPU backend.

gstaichi.lang.misc.arm64[source]#: The ARM CPU backend.

gstaichi.lang.misc.cuda[source]#: The CUDA backend.

gstaichi.lang.misc.amdgpu[source]#: The AMDGPU backend.

gstaichi.lang.misc.metal[source]#: The Apple Metal backend.

gstaichi.lang.misc.vulkan[source]#: The Vulkan backend.

gstaichi.lang.misc.gpu[source]#

A list of GPU backends supported on the current system. Currently contains ‘cuda’, ‘metal’, ‘vulkan’, ‘amdgpu’.

When this is used, GsTaichi automatically picks the matching GPU backend. If no GPU is detected, GsTaichi falls back to the CPU backend.

gstaichi.lang.misc.cpu[source]#

A list of CPU backends supported on the current system. Currently contains ‘x64’, ‘x86_64’, ‘arm64’.

When this is used, GsTaichi automatically picks the matching CPU backend.

gstaichi.lang.misc.extension[source]#

An instance of GsTaichi extension.

The list of currently available extensions is [‘sparse’, ‘quant’, ‘mesh’, ‘quant_basic’, ‘data64’, ‘adstack’, ‘bls’, ‘assertion’, ‘extfunc’].

gstaichi.lang.misc.reset()[source]#

Resets GsTaichi to its initial state. This will destroy all the allocated fields and kernels, and restore the runtime to its default configuration.

Example:

>>> a = ti.field(ti.i32, shape=())
>>> a[None] = 1
>>> print("before reset: ", a)
before rest: 1
>>>
>>> ti.reset()
>>> print("after reset: ", a)
# will raise error because a is unavailable after reset.

gstaichi.lang.misc.init(arch=None, default_fp=None, default_ip=None, _test_mode: bool = False, enable_fallback: bool = True, require_version: str | None = None, print_non_pure: bool = False, src_ll_cache: bool = True, **kwargs)[source]#

Initializes the GsTaichi runtime.

This should always be the entry point of your GsTaichi program. Most importantly, it sets the backend used throughout the program.

Parameters:

arch – Backend to use. This is usually cpu or gpu.
default_fp (Optional[type]) – Default floating-point type.
default_ip (Optional[type]) – Default integral type.
require_version – A version string.
print_non_pure – Print the names of kernels, at the time they are executed, which are not annotated with @ti.pure
src_ll_cache – enable SRC-LL-CACHE, which will accelerate loading from cache, across all architectures, for pure kernels (i.e. kernels declared as @ti.pure)
**kwargs –
GsTaichi provides highly customizable compilation through kwargs, which allows for fine grained control of GsTaichi compiler behavior. Below we list some of the most frequently used ones. For a complete list, please check out taichi-dev/gstaichi.
- cpu_max_num_threads (int): Sets the number of threads used by the CPU thread pool.
- debug (bool): Enables the debug mode, under which GsTaichi does a few more things like boundary checks.
- print_ir (bool): Prints the CHI IR of the GsTaichi kernels.
*offline_cache (bool): Enables offline cache of the compiled kernels. Default to True. When this is enabled GsTaichi will cache compiled kernel on your local disk to accelerate future calls. *random_seed (int): Sets the seed of the random generator. The default is 0.

gstaichi.lang.misc.no_activate(*args)[source]#: Deactivates a SNode pointer.

gstaichi.lang.misc.block_local(*args)[source]#

Hints GsTaichi to cache the fields and to enable the BLS optimization.

Please visit https://docs.taichi-lang.org/docs/performance for how BLS is used.

Parameters:: *args (List[Field]) – A list of sparse GsTaichi fields.

gstaichi.lang.misc.mesh_local(*args)[source]#

Hints the compiler to cache the mesh attributes and to enable the mesh BLS optimization, only available for backends supporting ti.extension.mesh and to use with mesh-for loop.

Related to taichi-dev/gstaichi#3608

Parameters:: *args (List[Attribute]) – A list of mesh attributes or fields accessed as attributes.

Examples:

# instantiate model
mesh_builder = ti.Mesh.tri()
mesh_builder.verts.place({
    'x' : ti.f32,
    'y' : ti.f32
})
model = mesh_builder.build(meta)

@ti.kernel
def foo():
    # hint the compiler to cache mesh vertex attribute `x` and `y`.
    ti.mesh_local(model.verts.x, model.verts.y)
    for v0 in model.verts: # mesh-for loop
        for v1 in v0.verts:
            v0.x += v1.y

gstaichi.lang.misc.cache_read_only(*args)[source]#

gstaichi.lang.misc.assume_in_range(val, base, low, high)[source]#

Hints the compiler that a value is between a specified range, for the compiler to perform scatchpad optimization, and return the value untouched.

The assumed range is [base + low, base + high).

Parameters:

val (Number) – The input value.
base (Number) – The base point for the range interval.
low (Number) – The lower offset relative to base (included).
high (Number) – The higher offset relative to base (excluded).

Returns:

Return the input value untouched.

Example:

>>> # hint the compiler that x is in range [8, 12).
>>> x = ti.assume_in_range(x, 10, -2, 2)
>>> x
10

gstaichi.lang.misc.loop_config(*, block_dim=None, serialize=False, parallelize=None, block_dim_adaptive=True, bit_vectorize=False)[source]#

Sets directives for the next loop

Parameters:

block_dim (int) – The number of threads in a block on GPU
serialize (bool) – Whether to let the for loop execute serially, serialize=True equals to parallelize=1
parallelize (int) – The number of threads to use on CPU
block_dim_adaptive (bool) – Whether to allow backends set block_dim adaptively, enabled by default
bit_vectorize (bool) – Whether to enable bit vectorization of struct fors on quant_arrays.

Examples:

@ti.kernel
def break_in_serial_for() -> ti.i32:
    a = 0
    ti.loop_config(serialize=True)
    for i in range(100):  # This loop runs serially
        a += i
        if i == 10:
            break
    return a

break_in_serial_for()  # returns 55

n = 128
val = ti.field(ti.i32, shape=n)
@ti.kernel
def fill():
    ti.loop_config(parallelize=8, block_dim=16)
    # If the kernel is run on the CPU backend, 8 threads will be used to run it
    # If the kernel is run on the CUDA backend, each block will have 16 threads.
    for i in range(n):
        val[i] = i

u1 = ti.types.quant.int(bits=1, signed=False)
x = ti.field(dtype=u1)
y = ti.field(dtype=u1)
cell = ti.root.dense(ti.ij, (128, 4))
cell.quant_array(ti.j, 32).place(x)
cell.quant_array(ti.j, 32).place(y)
@ti.kernel
def copy():
    ti.loop_config(bit_vectorize=True)
    # 32 bits, instead of 1 bit, will be copied at a time
    for i, j in x:
        y[i, j] = x[i, j]

gstaichi.lang.misc.global_thread_idx()[source]#

Returns the global thread id of this running thread, only available for cpu and cuda backends.

For cpu backends this is equal to the cpu thread id, For cuda backends this is equal to block_id * block_dim + thread_id.

Example:

>>> f = ti.field(ti.f32, shape=(16, 16))
>>> @ti.kernel
>>> def test():
>>>     for i in ti.grouped(f):
>>>         print(ti.global_thread_idx())
>>>
test()

gstaichi.lang.misc.mesh_patch_idx()[source]#

Returns the internal mesh patch id of this running thread, only available for backends supporting ti.extension.mesh and to use within mesh-for loop.

Related to taichi-dev/gstaichi#3608

gstaichi.lang.misc#

Attributes#

Functions#

Module Contents#

This Page