codegen optimization plan

Author: Mohamed Koubaa

AGENTS.md

@@ -3,6 +3,10 @@ Assume an appropriate virtual environment is activated. If it isn't, just abort.
 
 ## Agent Hints
 
+**CRITIAL: Ensure working directory**. Sometimes agents will change working directories as part of tasks and forget to change them back.
+pydyna agent documentation and scripts are often sensitive to working directory, so recommended to check the pwd before each agent operation
+if unsure.
+
 **CRITICAL: Never redirect output to /dev/null on Windows**. This triggers a VS Code security prompt that halts execution. Instead:
 - For commands where you want to suppress output: Use `>$null 2>&1` (PowerShell) or just run the command without redirection
 - For commands where you want to check output: Use `python codegen/generate.py 2>&1 | Out-Null` or capture in a variable
@@ -13,13 +17,16 @@ Assume an appropriate virtual environment is activated. If it isn't, just abort.
   - ✅ GOOD: `python codegen/generate.py` (no redirection)
   - ✅ GOOD: `$output = python codegen/generate.py 2>&1`
 
-**Documentation builds**: To build docs without examples, use:
+**Documentation builds**: To build docs without examples:
+
+Ensure that the python3.13 environment is active, then:
+
 ```bash
 # Build docs without examples or autokeywords (fast)
-cd doc && BUILD_EXAMPLES=false BUILD_AUTOKEYWORDS_API=false ./make.bat html
+BUILD_EXAMPLES=false BUILD_AUTOKEYWORDS_API=false ./doc/make.bat html
 
 # Build docs with autokeywords but no examples (slow, ~8+ min for keyword imports alone)
-cd doc && BUILD_EXAMPLES=false BUILD_AUTOKEYWORDS_API=true ./make.bat html
+BUILD_EXAMPLES=false BUILD_AUTOKEYWORDS_API=true ./doc/make.bat html
 ```
 
 ## Agent Coding Style Preferences

codegen/generate.py

@@ -98,10 +98,18 @@ def skip_generate_keyword_class(keyword: str) -> bool:
     return False
 
 
-def get_undefined_alias_keywords(keywords_list: typing.List[typing.Dict]) -> typing.List[typing.Dict]:
+def get_undefined_alias_keywords(keywords_list: typing.List[typing.Dict], subset_domains: typing.Optional[typing.List[str]] = None) -> typing.List[typing.Dict]:
+    from keyword_generation.utils.domain_mapper import get_keyword_domain
+
     undefined_aliases: typing.List[typing.Dict] = []
     for alias, kwd in data_model.ALIAS_TO_KWD.items():
         if alias not in [kwd["name"] for kwd in keywords_list]:
+            # Filter by subset domains if specified
+            if subset_domains:
+                domain = get_keyword_domain(alias)
+                if domain not in subset_domains:
+                    continue
+
             fixed_keyword = fix_keyword(alias).lower()
             classname = get_classname(fixed_keyword)
             fixed_base_keyword = fix_keyword(kwd).lower()
@@ -251,20 +259,31 @@ def generate_autodoc_file(autodoc_output_path, all_keywords, env):
     logger.info(f"Generated index.rst with {len(categories)} category links")
 
 
-def get_keywords_to_generate(kwd_name: typing.Optional[str] = None) -> typing.List[typing.Dict]:
+def get_keywords_to_generate(kwd_name: typing.Optional[str] = None, subset_domains: typing.Optional[typing.List[str]] = None) -> typing.List[typing.Dict]:
     """Get keywords to generate. If a kwd name is not none, only generate
-    it and its generations."""
+    it and its generations. If subset_domains is provided, only generate keywords
+    from those domains (e.g., ['boundary', 'contact', 'control'])."""
     assert data_model.KWDM_INSTANCE is not None, "KWDM_INSTANCE not initialized"
     keywords = []
     kwd_list = data_model.KWDM_INSTANCE.get_keywords_list()
 
     # first get all aliases
     add_aliases(kwd_list)
 
+    # Import domain mapper to properly determine keyword domain
+    from keyword_generation.utils.domain_mapper import get_keyword_domain
+
     # then get keywords to generate
     for keyword in kwd_list:
         if kwd_name != None and keyword != kwd_name:
             continue
+
+        # Filter by subset domains if specified
+        if subset_domains:
+            domain = get_keyword_domain(keyword)
+            if domain not in subset_domains:
+                continue
+
         for keyword, keyword_options in get_generations(keyword):
             item = get_keyword_item(keyword)
             item["options"] = keyword_options
@@ -273,16 +292,19 @@ def get_keywords_to_generate(kwd_name: typing.Optional[str] = None) -> typing.Li
     return keywords
 
 
-def generate_classes(lib_path: str, kwd_name: typing.Optional[str] = None, autodoc_output_path: str = "") -> None:
+def generate_classes(lib_path: str, kwd_name: typing.Optional[str] = None, autodoc_output_path: str = "", subset_domains: typing.Optional[typing.List[str]] = None) -> None:
     """Generates the keyword classes, importer, and type-mapper
     if kwd_name is not None, this only generates that particular keyword class
+    if subset_domains is not None, only generates keywords from those domains
     """
-    logger.debug(f"Starting class generation with lib_path={lib_path}, kwd_name={kwd_name}")
+    logger.debug(f"Starting class generation with lib_path={lib_path}, kwd_name={kwd_name}, subset_domains={subset_domains}")
+    if subset_domains:
+        logger.info(f"Subset mode: generating only domains {subset_domains}")
     autodoc_entries = []
     env = Environment(loader=get_loader(), trim_blocks=True, lstrip_blocks=True)
     output_manager = OutputManager(lib_path)
     # Generate only requested keyword(s)
-    keywords_list = get_keywords_to_generate(kwd_name)
+    keywords_list = get_keywords_to_generate(kwd_name, subset_domains)
     logger.info(f"Generating {len(keywords_list)} keyword classes")
     generated_count = 0
     skipped_count = 0
@@ -304,9 +326,9 @@ def generate_classes(lib_path: str, kwd_name: typing.Optional[str] = None, autod
 
     # Always rewrite autodoc for all keywords
     if autodoc_output_path and not kwd_name:
-        all_keywords = get_keywords_to_generate()
+        all_keywords = get_keywords_to_generate(subset_domains=subset_domains)
         generate_autodoc_file(autodoc_output_path, all_keywords, env)
-    keywords_list.extend(get_undefined_alias_keywords(keywords_list))
+    keywords_list.extend(get_undefined_alias_keywords(keywords_list, subset_domains))
     if kwd_name == None:
         generate_entrypoints(env, output_manager, keywords_list)
 
@@ -349,23 +371,35 @@ def run_codegen(args):
         return
     load_inputs(this_folder, args)
 
+    # Handle subset domains
+    subset_domains = None
+    if args.subset:
+        subset_domains = [d.strip() for d in args.subset.split(",")]
+        logger.info(f"Subset mode enabled: generating only {subset_domains} domains")
+
     # Handle autodoc-only mode
     if args.autodoc_only:
         logger.info("Generating autodoc files only")
         env = Environment(loader=get_loader(), trim_blocks=True, lstrip_blocks=True)
-        all_keywords = get_keywords_to_generate()
+        all_keywords = get_keywords_to_generate(subset_domains=subset_domains)
         generate_autodoc_file(autodoc_path, all_keywords, env)
         logger.info("Autodoc generation complete")
         return
 
+    # Handle subset domains
+    subset_domains = None
+    if args.subset:
+        subset_domains = [d.strip() for d in args.subset.split(",")]
+        logger.info(f"Subset mode enabled: generating only {subset_domains} domains")
+
     if args.keyword == "":
         kwd = None
-        logger.info("Generating code for all keywords")
-        generate_classes(output, autodoc_output_path=autodoc_path)
+        logger.info("Generating code for all keywords" if not subset_domains else f"Generating subset: {subset_domains}")
+        generate_classes(output, autodoc_output_path=autodoc_path, subset_domains=subset_domains)
     else:
         kwd = args.keyword
         logger.info(f"Generating code for {kwd}")
-        generate_classes(output, kwd, autodoc_output_path=autodoc_path)
+        generate_classes(output, kwd, autodoc_output_path=autodoc_path, subset_domains=subset_domains)
 
 
 def parse_args():
@@ -419,6 +453,12 @@ def parse_args():
         choices=["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"],
         help="Set the logging level. Defaults to INFO.",
     )
+    parser.add_argument(
+        "--subset",
+        "-s",
+        default="",
+        help="Generate only a subset of keyword domains (comma-delimited list, e.g., 'boundary,contact,control'). Useful for fast iteration during optimization work.",
+    )
     return parser.parse_args()
 
 

doc/Makefile

@@ -3,7 +3,8 @@
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
-SPHINXOPTS    = -j auto
+SPHINXJOBS    ?= auto
+SPHINXOPTS    = -j $(SPHINXJOBS)
 SPHINXBUILD   = sphinx-build
 SOURCEDIR     = source
 BUILDDIR      = _build
@@ -24,7 +25,10 @@ keyword_classes:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@echo "⏱️  Starting Sphinx build with -j $(SPHINXJOBS)..."
+	@echo "Build started at $$(date '+%Y-%m-%d %H:%M:%S')"
+	@time $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@echo "Build finished at $$(date '+%Y-%m-%d %H:%M:%S')"
 
 clean:
 	rm -rf $(BUILDDIR)/*

doc/make.bat

@@ -11,6 +11,11 @@ set SOURCEDIR=source
 set BUILDDIR=_build
 set APIDIR=source\api
 
+REM Set parallel build option (use SPHINXJOBS environment variable or default to auto)
+if "%SPHINXJOBS%" == "" (
+	set SPHINXJOBS=auto
+)
+
 if "%1" == "" goto help
 if "%1" == "clean" goto clean
 if "%1" == "pdf" goto pdf
@@ -28,7 +33,12 @@ if errorlevel 9009 (
 	exit /b 1
 )
 
-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+echo Starting Sphinx build with -j %SPHINXJOBS%...
+echo Build started at %TIME%
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% -j %SPHINXJOBS% %SPHINXOPTS% %O%
+set BUILD_EXIT_CODE=%ERRORLEVEL%
+echo Build finished at %TIME%
+exit /b %BUILD_EXIT_CODE%
 goto end
 
 :clean

doc/profile_build.py

@@ -0,0 +1,49 @@
+"""Profile the Sphinx documentation build."""
+
+import os
+import sys
+from pathlib import Path
+from pyinstrument import Profiler
+
+# Set environment variables before importing Sphinx
+os.environ['BUILD_EXAMPLES'] = 'false'
+os.environ['BUILD_AUTOKEYWORDS_API'] = 'true'
+os.environ['SPHINXJOBS'] = '1'
+
+# Add source directory to path
+doc_dir = Path(__file__).parent
+source_dir = doc_dir / 'source'
+build_dir = doc_dir / '_build'
+
+# Start profiling
+profiler = Profiler()
+profiler.start()
+
+# Import and run Sphinx
+from sphinx.cmd.build import main as sphinx_main
+
+sys.argv = [
+    'sphinx-build',
+    '-M', 'html',
+    str(source_dir),
+    str(build_dir),
+    '-j', '1'
+]
+
+try:
+    sphinx_main(sys.argv[1:])
+finally:
+    # Stop profiling and save results
+    profiler.stop()
+    
+    # Print to console
+    print("\n" + "=" * 80)
+    print("PROFILING RESULTS")
+    print("=" * 80)
+    profiler.print(show_all=False)
+    
+    # Save HTML report
+    html_output = build_dir / 'profile.html'
+    with open(html_output, 'w') as f:
+        f.write(profiler.output_html())
+    print(f"\nHTML profile saved to: {html_output}")

doc/source/conf.py

@@ -8,7 +8,13 @@
 from sphinx.builders.latex import LaTeXBuilder
 from sphinx_gallery.sorting import FileNameSortKey
 
-from ansys.dyna.core import __version__
+# Get version without importing the package (avoids triggering imports during conf.py execution)
+# This allows doc builds to work with subset-generated keywords
+try:
+    from importlib.metadata import version as importlib_version
+    __version__ = importlib_version("ansys-dyna-core")
+except Exception:
+    __version__ = "unknown"
 
 LaTeXBuilder.supported_image_types = ["image/png", "image/pdf", "image/svg+xml"]
 
@@ -169,9 +175,12 @@
 
 suppress_warnings = ["autoapi.python_import_resolution", "config.cache", "docutils"]
 
-BUILD_AUTOKEYWORS_API = os.environ.get("BUILD_AUTOKEYWORS_API", "false").lower() == "true"
-if BUILD_AUTOKEYWORS_API:
+BUILD_AUTOKEYWORDS_API = os.environ.get("BUILD_AUTOKEYWORDS_API", "false").lower() == "true"
+
+if BUILD_AUTOKEYWORDS_API:
     html_theme_options["ansys_sphinx_theme_autoapi"]["templates"] = "autoapi/"
+    # Remove the auto-generated keywords from the ignore list
+    html_theme_options["ansys_sphinx_theme_autoapi"]["ignore"] = []
 
 BUILD_EXAMPLES = os.environ.get("BUILD_EXAMPLES", "true").lower() == "true"
 if BUILD_EXAMPLES:
@@ -233,4 +242,78 @@ def skip_run_subpackage(app, what, name, obj, skip, options):
 
 def setup(sphinx):
     """Add custom extensions to Sphinx."""
-    sphinx.connect("autoapi-skip-member", skip_run_subpackage)
+    sphinx.connect("autoapi-skip-member", skip_run_subpackage)
+
+    # Add timing instrumentation for performance profiling
+    import time
+    import os
+    from pathlib import Path
+
+    # Create timing log file
+    timing_log = Path(__file__).parent.parent / "_build" / "timing.log"
+    timing_log.parent.mkdir(parents=True, exist_ok=True)
+
+    # Track phase timings
+    phase_times = {}
+
+    def log_time(phase, duration=None):
+        """Log timing information to file."""
+        if duration is None:
+            # Start timing
+            phase_times[phase] = time.time()
+            msg = f"[{time.strftime('%H:%M:%S')}] Starting: {phase}\n"
+        else:
+            # End timing
+            msg = f"[{time.strftime('%H:%M:%S')}] Completed: {phase} ({duration:.2f}s)\n"
+
+        with open(timing_log, "a") as f:
+            f.write(msg)
+        print(msg.strip())
+
+    # Event handlers
+    def on_builder_inited(app):
+        log_time("builder-init")
+        log_time("overall-build")
+
+    def on_env_get_outdated(app, env, added, changed, removed):
+        if "builder-init" in phase_times:
+            log_time("builder-init", time.time() - phase_times["builder-init"])
+        log_time("env-get-outdated")
+        return []
+
+    def on_env_before_read_docs(app, env, docnames):
+        if "env-get-outdated" in phase_times:
+            log_time("env-get-outdated", time.time() - phase_times["env-get-outdated"])
+        log_time("read-docs")
+
+    def on_doctree_resolved(app, doctree, docname):
+        # Only log first and every 100th document to avoid spam
+        if not hasattr(on_doctree_resolved, "count"):
+            on_doctree_resolved.count = 0
+        on_doctree_resolved.count += 1
+        if on_doctree_resolved.count == 1:
+            if "read-docs" in phase_times:
+                log_time("read-docs", time.time() - phase_times["read-docs"])
+            log_time("process-doctrees")
+
+    def on_build_finished(app, exception):
+        if hasattr(on_doctree_resolved, "count"):
+            if "process-doctrees" in phase_times:
+                log_time("process-doctrees", time.time() - phase_times["process-doctrees"])
+        if "overall-build" in phase_times:
+            log_time("overall-build", time.time() - phase_times["overall-build"])
+
+        # Summary
+        with open(timing_log, "a") as f:
+            f.write(f"\n{'='*60}\n")
+            f.write(f"Build completed at {time.strftime('%Y-%m-%d %H:%M:%S')}\n")
+            if hasattr(on_doctree_resolved, "count"):
+                f.write(f"Total documents processed: {on_doctree_resolved.count}\n")
+            f.write(f"{'='*60}\n")
+
+    # Connect event handlers
+    sphinx.connect("builder-inited", on_builder_inited)
+    sphinx.connect("env-get-outdated", on_env_get_outdated)
+    sphinx.connect("env-before-read-docs", on_env_before_read_docs)
+    sphinx.connect("doctree-resolved", on_doctree_resolved)
+    sphinx.connect("build-finished", on_build_finished)