From 91e5a92428cb4c21624745f06ef1818fa41a6113 Mon Sep 17 00:00:00 2001 From: neozhaoliang Date: Tue, 8 Mar 2022 11:54:37 +0800 Subject: [PATCH 1/4] update docstring for functions in misc.py --- python/taichi/_logging.py | 57 ++++++++++++++++++++++++++------------ python/taichi/lang/misc.py | 31 +++++++++++++++++---- 2 files changed, 66 insertions(+), 22 deletions(-) diff --git a/python/taichi/_logging.py b/python/taichi/_logging.py index 32fb3ed4d27a5..aa8ace69f8c64 100644 --- a/python/taichi/_logging.py +++ b/python/taichi/_logging.py @@ -34,50 +34,73 @@ def set_logging_level(level): See also https://docs.taichi.graphics/lang/articles/contribution/utilities#logging. Args: - level (str): The string represents logging level. + level (str): The string represents logging level.\ Effective levels include: 'trace', 'debug', 'info', 'warn', 'error', 'critical'. - Example: - >>> set_logging_level('debug') + Example:: - If call this function, then everything below 'debug' will be effective, - and 'trace' won't since it's above debug. + >>> set_logging_level('debug') """ ti_core.set_logging_level(level) def is_logging_effective(level): - """Check if the level is effective. The level below current level will be effective. - If not set by manual, the pre-set logging level is 'info'. + """Check if the specified logging level is effective. + All levels below current level will be effective. + The default level is 'info'. See also https://docs.taichi.graphics/lang/articles/contribution/utilities#logging. Args: - level (str): The string represents logging level. + level (str): The string represents logging level. \ Effective levels include: 'trace', 'debug', 'info', 'warn', 'error', 'critical'. Returns: - Bool: Indicate whether the logging level is supported. + Bool: Indicate whether the logging level is effective. - Example: - If current level is 'info': + Example:: - >>> print(ti.is_logging_effective("trace")) # False - >>> print(ti.is_logging_effective("debug")) # False - >>> print(ti.is_logging_effective("info")) # True - >>> print(ti.is_logging_effective("warn")) # True - >>> print(ti.is_logging_effective("error")) # True - >>> print(ti.is_logging_effective("critical")) # True + >>> # assume current level is 'info' + >>> print(ti.is_logging_effective("trace")) # False + >>> print(ti.is_logging_effective("debug")) # False + >>> print(ti.is_logging_effective("info")) # True + >>> print(ti.is_logging_effective("warn")) # True + >>> print(ti.is_logging_effective("error")) # True + >>> print(ti.is_logging_effective("critical")) # True """ return ti_core.logging_effective(level) +# ------------------------ DEBUG = 'debug' +"""The `str` 'debug', used for the `debug` logging level. +""" +# ------------------------ + TRACE = 'trace' +"""The `str` 'trace', used for the `debug` logging level. +""" +# ------------------------ + INFO = 'info' +"""The `str` 'info', used for the `info` logging level. +""" +# ------------------------ + WARN = 'warn' +"""The `str` 'warn', used for the `warn` logging level. +""" +# ------------------------ + ERROR = 'error' +"""The `str` 'error', used for the `error` logging level. +""" +# ------------------------ + CRITICAL = 'critical' +"""The `str` 'critical', used for the `critical` logging level. +""" +# ------------------------ supported_log_levels = [DEBUG, TRACE, INFO, WARN, ERROR, CRITICAL] diff --git a/python/taichi/lang/misc.py b/python/taichi/lang/misc.py index f682c39d26e5a..e474108e9d64d 100644 --- a/python/taichi/lang/misc.py +++ b/python/taichi/lang/misc.py @@ -172,6 +172,12 @@ type_factory_ = _ti_core.get_type_factory_instance() extension = _ti_core.Extension +"""An instance of Taichi extension. + +The list of currently available extensions is ['sparse', 'async_mode', 'quant', \ + 'mesh', 'quant_basic', 'data64', 'adstack', 'bls', 'assertion', \ + 'extfunc', 'packed', 'dynamic_index']. +""" def is_extension_supported(arch, ext): @@ -189,8 +195,19 @@ def is_extension_supported(arch, ext): def reset(): """Resets Taichi to its initial state. + This will destroy all the allocated fields and kernels, and restore + the runtime to its default configuration. + + Example:: - This would destroy all the fields and kernels. + >>> 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. """ impl.reset() global runtime @@ -504,8 +521,10 @@ def parallelize(v): serialize = lambda: parallelize(1) -def block_dim(v): - get_runtime().prog.current_ast_builder().block_dim(v) +def block_dim(dim): + """Set the number of threads in a block to `dim`. + """ + get_runtime().prog.current_ast_builder().block_dim(dim) def global_thread_idx(): @@ -545,7 +564,8 @@ def Tape(loss, clear_gradients=True): >>> y[None] += x[I] ** a >>> >>> with ti.Tape(loss = y): - >>> sum(2)""" + >>> sum(2) + """ impl.get_runtime().materialize() if len(loss.shape) != 0: raise RuntimeError( @@ -564,7 +584,8 @@ def Tape(loss, clear_gradients=True): def clear_all_gradients(): - """Set all fields' gradients to 0.""" + """Set the gradients of all fields to zero. + """ impl.get_runtime().materialize() def visit(node): From e0754a0860ad7665fa14365275db31d9f8d8b9ad Mon Sep 17 00:00:00 2001 From: Taichi Gardener Date: Tue, 8 Mar 2022 03:59:10 +0000 Subject: [PATCH 2/4] Auto Format --- python/taichi/_logging.py | 1 + 1 file changed, 1 insertion(+) diff --git a/python/taichi/_logging.py b/python/taichi/_logging.py index aa8ace69f8c64..4102ff702c4e9 100644 --- a/python/taichi/_logging.py +++ b/python/taichi/_logging.py @@ -70,6 +70,7 @@ def is_logging_effective(level): """ return ti_core.logging_effective(level) + # ------------------------ DEBUG = 'debug' From 01609ec70eb175c933daf0a96f52371679e1a57e Mon Sep 17 00:00:00 2001 From: Zhao Liang Date: Tue, 8 Mar 2022 14:59:45 +0800 Subject: [PATCH 3/4] Update _logging.py --- python/taichi/_logging.py | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/python/taichi/_logging.py b/python/taichi/_logging.py index 4102ff702c4e9..0487da7b18417 100644 --- a/python/taichi/_logging.py +++ b/python/taichi/_logging.py @@ -29,13 +29,17 @@ def logger(msg, *args, **kwargs): def set_logging_level(level): - """Controls the level of detail in logs. + """Setting the logging level to a specified value. + Available levels are: 'trace', 'debug', 'info', 'warn', 'error', 'critical'. + + Note that after calling this function, logging levels below the specified one will + also be effective. For example if `level` is set to 'warn', then the levels below + it, which are 'error' and 'critical' in this case, will also be effective. See also https://docs.taichi.graphics/lang/articles/contribution/utilities#logging. Args: - level (str): The string represents logging level.\ - Effective levels include: 'trace', 'debug', 'info', 'warn', 'error', 'critical'. + level (str): Logging level. Example:: From 0a64d453530e11749cc5fb2099600fc6a1c58743 Mon Sep 17 00:00:00 2001 From: Taichi Gardener Date: Tue, 8 Mar 2022 07:29:24 +0000 Subject: [PATCH 4/4] Auto Format --- python/taichi/_logging.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/python/taichi/_logging.py b/python/taichi/_logging.py index 0487da7b18417..29696b9fe062d 100644 --- a/python/taichi/_logging.py +++ b/python/taichi/_logging.py @@ -31,15 +31,15 @@ def logger(msg, *args, **kwargs): def set_logging_level(level): """Setting the logging level to a specified value. Available levels are: 'trace', 'debug', 'info', 'warn', 'error', 'critical'. - + Note that after calling this function, logging levels below the specified one will also be effective. For example if `level` is set to 'warn', then the levels below - it, which are 'error' and 'critical' in this case, will also be effective. + it, which are 'error' and 'critical' in this case, will also be effective. See also https://docs.taichi.graphics/lang/articles/contribution/utilities#logging. Args: - level (str): Logging level. + level (str): Logging level. Example::