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

[Example] Refactor example library #2475

Merged
merged 20 commits into from
Jul 6, 2021

Conversation

victoriacity
Copy link
Member

@victoriacity victoriacity commented Jun 30, 2021

A substantial amount of example programs have been added into Taichi since the past year. With a well-organized examples/ directory and adequate documentation for the example programs, not only can users have a clearer idea of Taichi's capabilities by navigating through and playing with the examples, but also will adding and reviewing new examples become more standardized.

This PR will introduce the following changes to the examples/ directory and documentation:

  • Make all example run without dependencies: currently all but mass_spring_3d and tree_gravity run without dependencies while these two exceptions require taichi_three and taichi_glsl packages.
  • Categorize examples: examples are now categorized as below:
  • examples/algorithms: Fundamental algorithms and data structures (MGPCG, spatial data structures, etc)
  • examples/chi_examples: Examples of CHI IR
  • examples/features: Features of Taichi compiler and frontend, including sparse computing, IO and GUI .
  • examples/ml: Machine learning and differentiable computing
  • examples/rendering: Rendering methods
  • examples/simulation: Physical simulations
  • Make categorized examples accessible to the ti executable
  • Documentation for examples and adding new examples (per [Doc] Remove all .rst docs #2492, this will be addressed separately due to ongoing documentation updates)

This PR is in draft stage and should not change anything out of the ti executable script, examples/ and docs/ directories. Inputs are welcome!

@victoriacity victoriacity changed the title [Examples] Refactor example library [Example] Refactor example library Jun 30, 2021
@yuanming-hu yuanming-hu self-requested a review July 1, 2021 05:35
@victoriacity
Copy link
Member Author

aha, why not ask user to install taichi_glsl and put utils there? Just ask me in wechat for pypi token!

@yuanming-hu and I agreed that all examples in the Taichi main repo should be self-contained. The goal of examples is to provide high-quality reference code snippets for new users to learn Taichi, so ideally examples would aim to be as concise and clear as possible.

Of course, introducing libraries will make the code even clearer (tree_gravity becomes evidently less intuitive after making it self-contained), so these examples will be eventually moved to the Advanced Examples repository where we can feel free to let users to install taichi_glsl and other libraries so that users can enjoy the contributions from Taichi extensions.

@yuanming-hu
Copy link
Member

yuanming-hu commented Jul 2, 2021

With a well-organized examples/ directory and adequate documentation for the example programs, not only can users have a clearer idea of Taichi's capabilities by navigating through and playing with the examples, but also will adding and reviewing new examples become more standardized.

I strongly agree that examples serve as the facade of a programming language. Examples should, at the very least,

  1. Represent Taichi code of the high quality;
  2. Be simple and concise (e.g., single file, easy to understand);
  3. Demonstrate the strengths of Taichi.

Many of the current examples do not satisfy these criteria and need to be removed (or moved to advanced examples after polishment). For example, I believe laplace.py (which I wrote 2 years ago) should be (sadly) removed - the demonstrated kernel leads to memory access out of bound, and may mislead readers. Note that laplace.py is used in some other files so we need to be careful. There are many other examples that are too complex for a newcomer (e.g., renderer.py, not really well written/documented).

@victoriacity and I will schedule a meeting to walk through all the examples.

@victoriacity victoriacity marked this pull request as ready for review July 6, 2021 02:20
Copy link
Member

@yuanming-hu yuanming-hu left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM! Just one nit :-)

examples/algorithm/marching_squares.py Outdated Show resolved Hide resolved
@victoriacity
Copy link
Member Author

/format

@rexwangcc
Copy link
Collaborator

rexwangcc commented Jul 6, 2021

(per [Doc] Remove all .rst docs #2492, this will be addressed in the docs repo)

Just a reminder that once #2494 is merged we should (and also make it clear to developers of the main repo) use this repo, not the docs repo as the source of truth of the documentation. The docs repo will become a mirrorred-content hosting repo + translations hub and only be updated if there are functional changes to the docsite itself.

@victoriacity victoriacity merged commit 3b81d2d into taichi-dev:master Jul 6, 2021
@k-ye k-ye mentioned this pull request Jul 6, 2021
@Leonz5288 Leonz5288 mentioned this pull request Jul 12, 2021
@k-ye k-ye mentioned this pull request Jul 27, 2021
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.

5 participants