Add a .geminiignore file and improve the Gemini style guide (#1004)

This adds a `.geminiignore` file to make Gemini CLI ignore a variety of
files that are not useful for it to look into.

This PR also adds more information to the `.gemini/styleguide.md` file.

Author: mhucka

.gemini/styleguide.md

@@ -2,9 +2,9 @@
 
 This style guide for Gemini outlines the coding conventions for this project.
 
-## General guidance
+## Introduction and goals
 
-### Overall principles
+### Overall goals
 
 *   _Readability_: Code must be easy for humans to understand. Prefer clarity
     over cleverness. Write elegant, well-structured code.
@@ -16,39 +16,68 @@ This style guide for Gemini outlines the coding conventions for this project.
 
 *   _Performance_: While readability is paramount, code should be efficient.
 
-### Overall development approach
+### Overall software engineering principles
 
-*   Code should be modular and adhere to language idioms and best practices.
+*   Write modular code that follows language idioms and best practices.
 
-*   Data obtained from the user or read from a file should be validated.
-    Identify and guard against potential vulnerabilities in data handling or
-    input validation.
+*   Prioritize numerical stability and accuracy. Keep in mind the limitations of
+    floating-point arithmetic (e.g., float, double).
 
-*   When new functions, classes, and files are introduced, they should also
-    have corresponding tests. Existing tests must continue to pass (or be
-    updated) when changes are introduced, and code should be covered by tests.
+*   Strive for performance through memory efficiency. Watch out for bottlenecks
+    due to memory access. Design data structures and algorithms to promote data
+    locality. Access memory sequentially (e.g., iterating through a
+    `std::vector`) to maximize cache hits.
 
-*   Test coverage must be high. We don't require 100% coverage, but any
-    uncovered code must be annotated appropriate directives (for example,
-    `# pragma: no cover` in Python).
+*   Design for vectorization and parallelism. Structure loops and data access
+    patterns to be friendly to compiler vectorization (SIMD). Avoid complex
+    control flow (if/else) inside tight loops where possible.
 
-*   Tests must be independent and must not rely on the state of other tests.
-    Setup and teardown functions should be used to create a clean environment
-    for each test run. External dependencies (e.g., databases, network services,
-    file system) must be mocked to ensure the test is isolated to the unit under
-    test.
+*   Validate all user and file-based data to guard against security
+    vulnerabilities.
 
-*   Make sure to cover edge cases: write tests for invalid inputs, null values,
-    empty arrays, zero values, and off-by-one errors.
+*   New code requires new tests. Ensure existing tests continue to pass or are
+    updated when making changes.
 
-*   Use asserts in tests intelligently. Test assertions should be specific:
-    instead of just asserting `true`, assert that a specific value equals an
-    expected value. Provide meaningful failure messages.
+*   Thoroughly test for edge cases, including invalid inputs, null values, empty
+    arrays, and off-by-one errors.
 
-### Overall code format conventions
+*   Keep tests independent. Use setup and teardown functions for clean
+    environments and mock all external dependencies.
 
-Quantum AI projects generally follows Google coding conventions, with a few
-changes. The following Google style guides are the starting points:
+## Development workflow
+
+### Before you start
+
+*   **CRITICAL**: before changing any file, first ask the user if they want to
+    create a git branch for the work you are about to do.
+
+### File naming conventions
+
+*   Regular file names should be in all lower case, using underscores as word
+    separators as needed. The names should indicate the purpose of the code in
+    the file, while also be kept as short as possible without compromising
+    understandability.
+
+*   Test files are usually named after the file they test but with a name
+    ending in `_test.py` or `_test.cc`. For example, `something.py` would have
+    tests in a file named `something_test.py`.
+
+### File structure conventions
+
+*   Files must end with a final newline, unless they are special files that do
+    not normally have ending newlines.
+
+### Git commit conventions
+
+*   Use `git commit` to commit changes to files as you work. Each commit should
+    encompass a subportion of your work that is conceptually related.
+
+*   Each commit must have a title and a description.
+
+### Code style conventions
+
+Follow these Google coding conventions, with some project-specific conventions
+noted below.
 
 *   [Google C++ Style Guide](
     https://google.github.io/styleguide/cppguide.html)
@@ -63,8 +92,7 @@ changes. The following Google style guides are the starting points:
     https://google.github.io/styleguide/shellguide.html)
 
 To learn this project's conventions for line length, indentation, and other
-details of coding style, please inspect the following configuration files (if
-present at the top level of this project repository):
+details of coding style, please inspect the following configuration files:
 
 *   [`.editorconfig`](../.editorconfig) for basic code editor configuration
     (e.g., indentation and line length) specified using the
@@ -83,14 +111,14 @@ present at the top level of this project repository):
 
 *   [`.yamllint.yaml`](../.yamllint.yaml) for YAML files.
 
-### Overall code comment conventions
+### Code comment conventions
 
-Every source file must begin with a header comment with the copyright and
-license. We use the Apache 2.0 license. Here is an example of the required file
-header for a Python language code file:
+Every source code file longer than 2 lines must begin with a header comment with
+the copyright and license. We use the Apache 2.0 license. Here is an example for
+Python code:
 
 ```python
-# Copyright 2025 Google LLC
+# Copyright 2026 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -123,6 +151,28 @@ For comments in other parts of the files, follow these guidelines:
 
 This section outlines coding conventions for Python code in this project.
 
+### Setting up a Python environment for development
+
+To set up a Python development environment, do the following:
+
+```shell
+python3 -m venv venv
+source venv/bin/activate
+pip install -U pip
+```
+
+If there is a `dev-requirements.txt` file in the directory, run
+
+```shell
+pip install -r requirements.txt -r dev-requirements.txt
+```
+
+otherwise, run
+
+```shell
+pip install -r requirements.txt --group dev
+```
+
 ### Python naming conventions
 
 This project follows some nomenclature rules and conventions in order to
@@ -137,7 +187,7 @@ naming, we can reduce cognitive load on human users and developers.
 
 *   _Functions_: Use lowercase with underscores (snake_case). Examples:
     `calculate_total()`, `process_data()`. Internal functions are prefixed with
-    an understore (`_`).
+    an underscore (`_`).
 
 *   _Classes_: Use CapWords (CamelCase). Examples: `UserManager`,
     `PaymentProcessor`.
@@ -164,7 +214,7 @@ naming, we can reduce cognitive load on human users and developers.
         amplitudes. If a function expects a NumPy array of amplitudes, its type
         annotation should be `np.ndarray`.
 
-###  Python docstrings and documentation
+### Python docstrings and documentation
 
 This project uses [Google style doc strings](
 http://google.github.io/styleguide/pyguide.html#381-docstrings) with a Markdown
@@ -212,7 +262,8 @@ def some_function(a: int, b: str) -> float:
 ### Python formatting
 
 Note: the Python code uses 88-column line widths, which is the default used by
-code the formatters `black` and `flynt`. (The C++ files use 80.)
+code the formatter `black` but not the [Google Python Style Guide](
+https://google.github.io/styleguide/pyguide.html). (The latter use 80.)
 
 The following programs can be used to perform some automated formatting.
 
@@ -236,7 +287,7 @@ where possible, especially on public classes and functions to serve as
 documentation, but also on internal code so that the `mypy` type checker can
 help catch coding errors.
 
-### Python linting
+### Linting Python code
 
 Python files:
 
@@ -246,7 +297,7 @@ Python files:
 
 *   `pylint -j0 .` will run `pylint` on all Python files.
 
-### Python testing
+### Testing Python code
 
 Unit and integration tests can be run for the Python portions of this project
 using the following command:
@@ -279,7 +330,7 @@ This section outlines coding conventions for C++ code in this project.
     *   A computational basis state (say, $|0000\rangle$) is typically
         referred to as a `bitstring`.
 
-### C++ formatting
+### Formatting C++ code
 
 Note: the C++ code files use 80-column line widths. (The Python files use 88.)
 
@@ -288,7 +339,7 @@ Note: the C++ code files use 80-column line widths. (The Python files use 88.)
 
 *   `clang-format -i PATH/TO/FILE` will reformat the file.
 
-#### C++ testing
+#### Testing C++ code
 
 If you only want to run tests for the core C++ libraries, use this command:
 
@@ -299,16 +350,22 @@ bazel test tests:all
 To build tests without running them, instead use:
 
 ```shell
-bzel build tests:all
+bazel build --config=verbose tests:all
 ```
 
 ## Shell script-specific guidance
 
 Shell scripts should use Bash.
 
-### Shell script formatting
+### Formatting shell scripts
 
 Use the [Google Shell Style Guide](
 https://google.github.io/styleguide/shellguide.html) with the following changes:
 
 *   Use indentation of 4 spaces, not 2.
+
+## TOML file-specific guidance
+
+### Formatting `.toml` files
+
+We use indentation of 4 spaces, not 2.

.geminiignore

@@ -0,0 +1,21 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Summary: tell Gemini CLI what it should or should not ignore. Takes precedence
+# over .gitignore (which Gemini CLI also reads), thus can be used to un-ignore
+# files that shouldn't be committed to git yet should be visible to Gemini. Also
+# used to ignore things usually in people's global .gitignore files.
+
+# Not in .gitignore because it's a git submodule. Tell Gemini to ignore it.
+/tests/googletest/

.gitignore

@@ -1,28 +1,68 @@
-# Generated files
-*.o
-*.a
-*.so
-*.x
-*.mod
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
 
-# Python cache
-__pycache__
-.ipynb_checkpoints
+# Summary: tell git what to ignore in the qsim source tree.
 
-# Build
-/build
-*.egg-info
+# Bazel files.
+/bazel-*
 
-# Bazel output
-bazel-*
+# Eigen is downloaded by our build files.
+eigen/
 
-.idea/*
+# Jupyter-specific items.
+*/.ipynb_checkpoints/
+.ipynb_checkpoints
+ipython_config.py
 
-# Eigen library
-eigen
+# Python-related items.
+*.coverage
+*.coverage.*
+*.egg
+*.egg-info/
+*.py,cover
+*.py[cod]
+.cache/
+.dmypy.json
+.mypy_cache/
+.pytest_cache/
+.pytype/
+.ruff_cache/
+__pycache__/
+build/
+dist/
+dmypy.json
+wheelhouse/
 
-# vscode
-.vscode/*
+# Python virtual environments (from instructions given to people).
+CirqDevEnv
+venv
+
+# Generated files.
+*.o
+*.a
+*.so
+*.x
+*.mod
 
-# Bazel files
-/bazel-*
+# Miscellaneous common editor backup files and temp files.
+*.bak
+*.swp
+*.tmp
+*~
+.\#*
+.idea/
+.vs
+.vscode/
+.~*~
+\#*\#