-
Notifications
You must be signed in to change notification settings - Fork 2.3k
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
[doc] Add user utilities doc #1295
[doc] Add user utilities doc #1295
Conversation
Codecov Report
@@ Coverage Diff @@
## master #1295 +/- ##
==========================================
+ Coverage 85.57% 86.14% +0.57%
==========================================
Files 19 19
Lines 3368 3543 +175
Branches 623 631 +8
==========================================
+ Hits 2882 3052 +170
- Misses 356 363 +7
+ Partials 130 128 -2
Continue to review full report at Codecov.
|
docs/user_utilities.rst
Outdated
@@ -0,0 +1,109 @@ | |||
User utilities |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Suggestion: Debugging utilities
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Good suggestion
docs/user_utilities.rst
Outdated
@ti.kernel | ||
def compute(): | ||
var[0] = 1.0 | ||
ti.info(f"set var[0] = 1.0") |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Let's be clear that this is only called at compile-time. i.e. If you recall compute, it won't reprint the string. (same as ti.static_print)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Agree.
I have an observation, would you please help me to check whether my understanding is correct?
According to the Debugging
part in this doc, It seems that all of the print
will be transfered to ti.static_print
by the AST preprocessor, so that they will be executed in run-time. That's good.
But it doesn't include logging utils such ti.info
, these ti.info
are only called at compiled-time but not runtime.
So we cannot do any logging ti.info
in kernel runtime, right? :( only print is supported in runtime is a little trivial, and IMO the debugging experince can be nicer if we support ti.info
in runtime.
Basically, why wasn't ti.info
be supported in runtime? It looks not very hard. Would you be happy to introduce the idea behind this design? :D
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It looks not very hard
No, copying strings from GPU to CPU is harder than you may think. Ancient GPUs doesn't even support integer, not to mention f-string...
introduce the idea behind this design?
The OpenGL backend for example, maintains
- An array of integer on GPU end (to prevent string operation on GPU)
- An string table on CPU end (CPU is rich, able to perform string operation)
The integers in GPU end are indices to the string table.
And when GPU kernel ends, we copy the array of integer, and according to string table, translate back to real strings.
However, ti.info
needs f-string to work (e.g. ti.info("x = {:02x}", x)
), which needs formatting integer to string according to the string content, this could obviously break the string table attempt.
In fact, the only difference between ti.info
and print
is its color and f-string.. I think print('x =', x)
is good enough, not sure why ti.info
superior.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for your clear explanation! I get the point. Yes, I fully understand your meaning. ;-)
The difference is just the timestamp(color is relatively unimportant). Let's assume we want to do a simulation which can cost for a whole day (It's quite common in mechanical and chemstry simulation, most of them are in reseach cases), If we want to find the bug after waking up in the morning, a timestamp or screenshot can be helpful IMAO.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think they could do ti.info
between kernel launches.
In fact, print
in kernel also won't print until kernel ends as my explanation goes above.
So there's no difference for this usage.
If you want a timestamp in print
, I think print(ti.timestamp(), 'x =', x)
is a good approach (where ti.timestamp()
is a runtime timestamp getter TBD).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks!
I will invesigate this case further more. I need to get a global view of Taichi in order to understand it, instead of floating on the surface. XD
docs/user_utilities.rst
Outdated
|
||
TODO: | ||
|
||
1. add ``ti.static_assert`` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Also add non-static assert
doc.
docs/user_utilities.rst
Outdated
|
||
1. more explanations and examples in this logging section. can we log a taichi tensor here, why and how? | ||
|
||
2. ``ti.error`` and ``ti.critical`` tested fail. I need to check it again |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
In fact, ti.error will purposely terminate the program, IIRC.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes, I think you are correct according to my experiment. ti.error
will cause a crash.
I can fully understand this design, but not very agree with it. Our loggging utility should focus on logging but not try to control the workflow of ANY Taichi
program.
For example, If I say:
ti.error("here is an error!")
I simply want to show this error to the screen but not crash in this place. It's also spdlog recommending.
HDYT?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That could be hard, since there's already many C++ code assuming TI_ERROR
to be program-terminating. IMHO if user want to show error without terminate, they may use ti.warn
or ti.critical
instead.
Or, if you insist to, feel free to add another higher-level like TI_PANIC
in another PR (not this PR).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Great, so let's keep ti.error
terminte the program and I will documted it on stress emphasize. :D
Sorry about my delayed comments.
We have two sets of profilers: #1261
This will be very helpful!
I guess that's because we rarely use them. For now, |
Thanks a lot for your powerful guide! So that I can investigate these 2 profilers deeply and documente them! Agree, I also think
|
The design of But I can only see its work in a single thread. Would you please give me some guides on a multi-threads case? |
Update: First sorry: I do Here is a new version I met with some new questions and got stuck when writing this doc. @archibate Would you be happy to give me some guidence? The questions are maintained in the beginning part. Thanks in advance! |
On my way! |
e87630e
to
f3ef2d6
Compare
@Rullec Fixed now, run |
Thanks!
彭于斌 <notifications@github.com> 于2020年6月28日周日 上午11:03写道:
… @Rullec <https://github.com/Rullec> Fixed now, run git pull --force to go
ahead.
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#1295 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AEAYDGXG6KSQCTDFUPQ2563RY2XGRANCNFSM4ODPFVPQ>
.
|
Update: Now there is a new version. Would be please give me some suggestions? |
Hi all, |
docs/user_utilities.rst
Outdated
import taichi as ti | ||
|
||
ti.init() | ||
ti.set_logging_level(ti.ERROR) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Let's remove this or user would think loglev has to be error to make error work.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Great!
docs/user_utilities.rst
Outdated
compute() | ||
ti.core.print_profile_info() | ||
|
||
``ti.core.print_profile_info()`` will output statistics in a hierarchical format, with different colors for different levels. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
OFT: Can we make this ti.print_profile_info?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Done, update comming soon.
docs/user_utilities.rst
Outdated
:: | ||
|
||
[ 22.73%] jit_evaluator_0_kernel_0_serial min 0.001 ms avg 0.001 ms max 0.001 ms total 0.000 s [ 1x] | ||
[ 0.00%] jit_evaluator_1_kernel_1_serial min 0.000 ms avg 0.000 ms max 0.000 ms total 0.000 s [ 1x] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
OFT: Can we make jit&accessor kernels invisible by default? They are usually 0 and confusing to end-users.
docs/user_utilities.rst
Outdated
.. code-block :: python | ||
:emphasize-lines: 1, 9 | ||
|
||
ti.init(ti.cpu, kernel_profiler = True) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Please leave no space around =
, see yapf.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks, a formatter has been introduced in now.
Hello? @Rullec are you still there? |
Sorry for my late reply, I'm on ddl for these 2 weeks! I will update it
hopefully 2 hrs later.
彭于斌 <notifications@github.com> 于2020年7月5日周日 下午12:52写道:
… Hello? @Rullec <https://github.com/Rullec> are you still there?
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#1295 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AEAYDGTV2EXXSGV34XGFW6DR2ABKHANCNFSM4ODPFVPQ>
.
|
Update:
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Cool! LGTM in general. I took a pass and fixed a few wording issues. Please take your time and no rush at all.
Hello? @Rullec are you still there?
@archibate please be courteous and friendly. We are an open-source community and nobody is obligated to contribute. Keep in mind that most people have their daily work to do. Thanks! :-)
Thanks both @archibate and @yuanming-hu , for your kindly comprehension and all of these powerful modifications. :D I will consider how to revise this doc again, and hopefully a new version can come soon. |
updated by yuanming Co-authored-by: Yuanming Hu <yuanming-hu@users.noreply.github.com>
Hi all, here is a new version. Most of problems we mentioned above has been treated in it. But I still have a question, @yuanming-hu said that |
Just invoke the kernel twice, and you'll find it's only printed once. |
But isn't that what we want? For example,
output:
It has been pointed out in our doc So I feel a little hard to understand why @yuanming-hu said using |
import taichi as ti
ti.init(arch=ti.cpu)
ti.set_logging_level(ti.INFO)
mat = ti.var(dt=ti.f32, shape=(5, 5))
@ti.func
def calc(i: ti.int32, j: ti.int32):
ti.info(f"set var in ti.func")
mat[i, j] = i * j
@ti.kernel
def compute():
calc(0, 0)
calc(1, 1)
calc(2, 2)
ti.info(f"set var in ti.kernel")
compute()
compute()
compute()
compute()
compute()
compute()
compute()
compute() users' expected output:
real output:
|
Yes, It seems we reaches an agreement. Here is a new example, would it be better? |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTMig + section position nits
docs/utilities.rst
Outdated
print(err) | ||
|
||
|
||
Profiler |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Profiler should be shared by devs and end-users, maybe we can have a separate .rst for it?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
IMO I think it's enough in utilities.rst
at this moment.
docs/utilities.rst
Outdated
@@ -1,25 +1,185 @@ | |||
Developer utilities | |||
=================== | |||
|
|||
|
|||
This section provides a detailed description of some commonly used utilities for Taichi developers. | |||
|
|||
Logging |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hi, sorry about dismissing your changes, I have already done with Logging
in #1475 :)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
May you merge these 2 changes into a single one? I also have no idea about how to deal with this conflict.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
To prevent conflicts with #1475, you may move the Profiler
to another section like profiler.rst
:) I'll try to merge conflicts in Logging
section once one of these two PR is merged.
Finished, as @archibate adviced, I remove all contents about |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thank for breaking the changeset down! This really help me review quicker ❤️ LGTMig
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Cool! Ready to merge after the wording issues are addressed. Thank you so much!
(The logging part is probably still useful as long as it's made more concise.)
Thank you all for your work as well! |
This reverts commit 5213b0d.
Related issue = Close #1269
[Click here for the format server]
This draft PR is for user utilities. I simply add a
user_utilities
inMISCELLANEOUS
part. Current Changes shows below.this logging moduleti.info
,Profiler
module for the first timesay something about: finished in [Lang] Add ti.static_assert for compile-time assertations #1344assertation
I still need to do:
1. Logging
I am not satisfied withti.info
this part. I think it can do more, for example display a tensor's value (under the help of precessor AST)A potential bug inti.error
orti.critical
, maybe we need to add a test script for this functionality.ti.critical
andti.CRITICAL
are missing, why?ti.info
is only executed once in compile-time. So what are the suitable scenarios for this command?: WIP, the same reason asti.static_print
in [Lang] Add ti.static_assert for compile-time assertations #1344: finished in [Lang] Add ti.static_assert for compile-time assertations #1344ti.static_print
is executed in compile-time as well. What are the suitable scenarios?I think we need to say that print doesn't support f-string, otherwise lots of guys need to try it and get confused. the same asti.info
andti.static_print
: maybe finished in [Lang] Add ti.static_assert for compile-time assertations #13442. Profiling
Our profiler is a little weak relatively. It can not do some very basic profilingProfiler doesn't work inti.cpu
: Need to test.Two profilers are needed to be documented.To distinguish our 2 profilersScopedProfiler
andProfilerBase
[perf] Refactor kernel profiler #1261, I used these 2 names directly in this doc. But they are hidden deeply in Taichi's core and should not be exposed to the end-user. Is there a better way to do that?profilers
, explain what these statistics stand for in detail. (Sadly I cannot understand all of them as well.)3. Asserting
doc python built-inassert
implement: finished in [Lang] Add ti.static_assert for compile-time assertations #1344ti.static_assert
. What feature do we want exactly inti.static_assert
, I am a little confused... :( Is it an assertation that works in runtime as well??doc: finished in [Lang] Add ti.static_assert for compile-time assertations #1344ti.static_assert
.All of these conculsions are my own and only temporary. Some of them may not be true but I need to verify it again and dig deeper.