_quarto.yml

project:
  type: website
  output-dir: _site
  # Render an explicit list rather than every .md/.qmd in the tree: research/
  # holds working notes that are not part of the documentation site, and
  # stray READMEs (docs/assets/**/README.md) are not pages either.
  render:
    - index.qmd
    - docs/*.qmd
    - reference/*.qmd
  resources:
    - docs/assets/**
    # The public demo, built by docs.yml (`npm run build:static` in
    # frontend/, copied to demo/); served as files, never rendered.
    - demo/**

# Written by `quartodoc build` (see `quartodoc.sidebar` below): the API
# reference sidebar, one entry per section and object.
metadata-files:
  - reference/_sidebar.yml

website:
  title: cadjoint
  description: Differentiable CAD with JAX and SDFs
  favicon: docs/assets/logo.svg
  # The sidebar shows where a page is; breadcrumbs above the title only
  # pushed nested pages' titles down.
  bread-crumbs: false
  search:
    location: navbar
    type: overlay
    limit: 30
  navbar:
    logo: docs/assets/logo.svg
    logo-alt: cadjoint
    title: CADJOINT
    right:
      - text: Demo
        href: demo/index.html
      - icon: github
        href: https://github.com/andrinr/cadjoint
  page-footer:
    left: "cadjoint"
    right:
      - text: Research notes (GitHub)
        href: https://github.com/andrinr/cadjoint/tree/main/research

format:
  html:
    theme: [cosmo, docs/assets/cadjoint.scss, docs/assets/tokens.scss]
    highlight-style: none
    toc: true
    toc-depth: 2
    toc-location: left
    code-copy: true
    # One navigation panel: docs/assets/nav.html nests the page outline under
    # the current page's entry in the sidebar.
    include-after-body: docs/assets/nav.html

execute:
  enabled: false  # render stored outputs, don't re-execute

quartodoc:
  package: cadjoint
  dir: reference
  title: API reference
  parser: google
  # One page per object; the index lists each object with its one-line
  # docstring summary.  Objects are documented at the path a user imports
  # them from (`construction.extrude`, not `construction.extrude.extrude`).
  # The one site sidebar. quartodoc writes it, splicing the reference
  # sections in at {{ contents }}; every page uses it.
  sidebar:
    file: reference/_sidebar.yml
    style: floating
    collapse-level: 1
    contents:
      - text: Overview
        href: index.qmd
      - docs/getting-started.qmd
      - section: Guides
        href: docs/guides.qmd
        contents:
          - docs/modelling.qmd
          - docs/meshing.qmd
          - docs/simulation.qmd
          - docs/materials.qmd
          - docs/optimization.qmd
          - docs/rendering.qmd
          - docs/plugins.qmd
          - docs/flow.qmd
      - docs/viewer.qmd
      - section: API reference
        href: reference/index.qmd
        contents:
          - "{{ contents }}"
  # quartodoc 0.11 renders every docstring section cadjoint uses except
  # Yields, and dies on the first generator or context manager it meets.
  # _quartodoc_renderer.py fills that one gap; drop it when upstream
  # renders Yields itself.
  renderer:
    style: _quartodoc_renderer.py
  sections:
    # -- Parameters & geometry ------------------------------------------------
    - title: Parameters and geometry
      desc: Scalar and vector parameters, and extraction of a tree's parameters.
    - subtitle: Parameters
      desc: Parameter types and helpers.
      contents:
        - geometry.Parameter
        - geometry.Scalar
        - geometry.Vector
        - geometry.Vector2
        - geometry.as_parameter
        - geometry.deduplicate_params
    - subtitle: Parameter extraction
      desc: Read free and fixed parameters from a tree; write values back.
      contents:
        - extract_parameters
        - apply_parameters

    # -- Sketches and construction -------------------------------------------
    - title: Sketches and construction
      desc: Sketch planes, 2D profiles, features that generate solids, and face references.
    - subtitle: Sketches
      desc: Work planes and closed polygon profiles.
      contents:
        - construction.SketchPlane
        - construction.PolygonProfile
    - subtitle: Features
      desc: Extrude, revolve and loft a profile into a solid.
      contents:
        - construction.extrude
        - construction.revolve
        - construction.loft
        - construction.Solid
        - construction.ConstructionPrimitive
    - subtitle: Face references
      desc: Faces and axes of generated solids, used to place sketch planes.
      contents:
        - construction.Face
        - construction.FaceSet
        - construction.Feature
        - construction.Axis

    # -- Constraints -----------------------------------------------------------
    - title: Constraints
      desc: Constraint types, the constraint solver, and degree-of-freedom analysis.
    - subtitle: Constraint types
      desc: One class per geometric relation.
      contents:
        - constraints.Constraint
        - constraints.DistanceConstraint
        - constraints.AngleConstraint
        - constraints.HorizontalConstraint
        - constraints.VerticalConstraint
        - constraints.CoincidentConstraint
        - constraints.FixedConstraint
        - constraints.EqualLengthConstraint
        - constraints.PointOnLineConstraint
        - constraints.ParallelConstraint
        - constraints.PerpendicularConstraint
        - constraints.ParallelEdgesConstraint
        - constraints.PerpendicularEdgesConstraint
    - subtitle: Solving and projection
      desc: Solve constraints and project parameters onto the constraint manifold or bounds.
      contents:
        - solve_constraints
        - constraints.satisfy_constraints
        - constraints.constraint_residuals
        - constraints.project_to_manifold
        - constraints.make_manifold_projection
        - constraints.project_bounds
        - constraints.make_bounds_projection
    - subtitle: Degrees of freedom
      desc: Residuals, parameter vectors and null-space maps.
      contents:
        - constraints.all_parameters
        - constraints.total_dof_reduction
        - constraints.build_residual_fn
        - constraints.compute_param_vector
        - constraints.unpack_param_vector
        - constraints.null_space
        - constraints.NullSpaceMap

    # -- Solids ----------------------------------------------------------------
    - title: Solids
      desc: SDF primitives, booleans, transforms, patterns and measures.
    - subtitle: Base class
      desc: Base class of all SDF nodes.
      contents:
        - SDF
    - subtitle: Primitives
      desc: Standard shapes and the polygon solids produced by construction features.
      contents:
        - sdf.Primitive
        - sdf.Box
        - sdf.RoundBox
        - sdf.Sphere
        - sdf.Cylinder
        - sdf.Capsule
        - sdf.Torus
        - sdf.Plane
        - sdf.primitives.ExtrudedPolygon
        - sdf.primitives.RevolvedPolygon
        - sdf.primitives.LoftedPolygon
        - sdf.primitives.polygon_sdf_2d
    - subtitle: Booleans
      desc: Union, intersection, difference, xor and smooth blends.
      contents:
        - sdf.Union
        - sdf.Intersection
        - sdf.Difference
        - sdf.Xor
        - sdf.BooleanOp
        - sdf.union
        - sdf.intersection
        - sdf.difference
        - sdf.xor
        - sdf.smooth_min
        - sdf.smooth_max
    - subtitle: Transforms
      desc: Affine transforms, deformations and field operations.
      contents:
        - sdf.Translate
        - sdf.Rotate
        - sdf.Scale
        - sdf.Twist
        - sdf.Shell
        - sdf.Offset
        - sdf.Mirror
        - sdf.shell
        - sdf.offset
        - sdf.mirror
    - subtitle: Patterns
      desc: Linear and polar patterns.
      contents:
        - sdf.LinearPattern
        - sdf.PolarPattern
        - sdf.linear_pattern
        - sdf.polar_pattern
    - subtitle: Measure
      desc: Volume and mass.
      contents:
        - sdf.volume
        - sdf.material_mass

    # -- Functionalize ---------------------------------------------------------
    - title: Functionalize and parametrization
      desc: Convert solids and scenes to pure functions of their parameters; reparametrize for optimization.
    - subtitle: Functionalize
      desc: SDF trees and scenes as pure functions of parameter dictionaries.
      contents:
        - functionalize
        - functionalize_scene
        - functionalize.functionalize_parametric
        - functionalize.functionalize_scene_parametric
    - subtitle: Parametrization
      desc: Unconstrained reparametrization and parameter scaling.
      contents:
        - to_unconstrained
        - to_constrained
        - compute_param_scales
        - normalize
        - unnormalize
        - to_normalized
        - from_normalized

    # -- Meshing ---------------------------------------------------------------
    - title: Meshing
      desc: Dual contouring from SDF to surface mesh, export and diagnostics.
    - subtitle: Extraction
      desc: "extract_mesh and its stages: grid sampling, edge crossings, QEF vertices, faces."
      contents:
        - meshing.extract_mesh
        - meshing.Mesh
        - meshing.GridSpec
        - meshing.sample_grid
        - meshing.find_crossing_edges
        - meshing.CrossingEdges
        - meshing.edge_hermite_data
        - meshing.HermiteData
        - meshing.detect_edges
        - meshing.qef_vertices
        - meshing.sharp_qef_vertices
        - meshing.dual_faces
    - subtitle: Sharp features
      desc: Face, crease and corner classification; active CSG branches.
      contents:
        - meshing.classify_feature_cells
        - meshing.FeatureCells
        - meshing.cell_edge_incidence
        - meshing.manifold_cell_incidence
        - meshing.CellIncidence
        - meshing.feature_cell_links
        - meshing.active_branches
        - meshing.detect_branch_changes
        - meshing.exact_feature_mask
        - meshing.ScenePatchFields
        - meshing.scene_patch_fields
        - meshing.world_frame_leaves
        - meshing.signature_function
        - meshing.patch_signatures
    - subtitle: Adaptive extraction and simplification
      desc: Sparse lattices, bounds fitting and simplification.
      contents:
        - meshing.surface_cells
        - meshing.sparse_crossing_edges
        - meshing.bounds.fit_bounds
        - meshing.bounds.boundary_inside
        - meshing.simplify_mesh
    - subtitle: Export and diagnostics
      desc: OBJ, STL and STEP export; mesh quality checks.
      contents:
        - meshing.save_obj
        - meshing.save_stl
        - meshing.save_step
        - meshing.remove_slivers
        - meshing.merge_planar_faces
        - meshing.mesh_report
        - meshing.surface_deviation
        - meshing.triangle_quality
        - meshing.self_intersections

    # -- Simulation ------------------------------------------------------------
    - title: Simulation
      desc: Simulation meshes, studies, boundary conditions, node selections, material properties and solver backends.
    - subtitle: Meshes
      desc: Simulation meshes and SDF-to-hex/tet meshing.
      contents:
        - fem.SimMesh
        - fem.HexMesh
        - fem.TetMesh
        - fem.sdf_to_hex_mesh
        - fem.sdf_to_tet_mesh
        - fem.recompute_points
        - fem.recompute_tet_points
        - fem.project_points
        - fem.Discretization
        - fem.Surface
        - fem.FaceGroup
        - fem.select_faces
        - fem.faces_from_nodes
        - fem.tet_faces_from_nodes
    - subtitle: Mesh quality
      desc: Element quality metrics.
      contents:
        - fem.scaled_jacobians
        - fem.aspect_ratios
        - fem.corner_tet_volumes
        - fem.tet_aspect_ratios
        - fem.tet_radius_ratios
    - subtitle: Studies
      desc: Thermal and elastic studies and their results.
      contents:
        - fem.ThermalStudy
        - fem.ElasticStudy
        - fem.SimulationResult
        - fem.ThermalProblem
        - fem.ElasticProblem
        - studies.capture_studies
        - studies.declared_studies
        - studies.register_study
        - fem.capture_sim_meshes
    - subtitle: Boundary conditions
      desc: Temperature, heat flux, fixed and traction conditions.
      contents:
        - fem.Dirichlet
        - fem.HeatFlux
        - fem.Fixed
        - fem.Traction
    - subtitle: Node selections
      desc: Selections of mesh nodes defined by position.
      contents:
        - studies.Nodes
        - studies.NodeSelection
        - studies.selection_from_description
        - studies.boundary_node_mask
        - studies.BoundaryMesh
    - subtitle: Material properties
      desc: Per-cell material properties sampled from the scene.
      contents:
        - fem.properties.sample_material_field
        - fem.properties.sample_cell_property
        - fem.properties.maybe_sample_cell_property
        - fem.properties.cell_centroids
        - fem.properties.cell_volumes
        - fem.properties.total_mass
        - fem.properties.quantize_to_materials
    - subtitle: Solver backends
      desc: Solver backend protocol and registry.
      contents:
        - fem.backends.SolverBackend
        - fem.backends.get_backend
        - fem.backends.register_backend
        - fem.backends.available_backends
    - subtitle: Gmsh tet meshing
      desc: Tet10 meshes through Gmsh and node ownership.
      contents:
        - fem.gmsh.gmsh_available
        - fem.gmsh.gmsh_version
        - fem.gmsh.sdf_gmsh_tet_mesh
        - fem.gmsh.gmsh_tet_mesh
        - fem.gmsh.tet_mesh_from_gmsh
        - fem.gmsh.GmshMesh
        - fem.gmsh.GmshTetMesh
        - fem.gmsh.gmsh_topology
        - fem.gmsh.dc_surface_stl
        - fem.gmsh.surface_stl
        - fem.gmsh.patch_table
        - fem.gmsh.design_values
        - fem.gmsh.snap_toward_patches
        - fem.gmsh.assign_ownership
        - fem.gmsh.owned_nodes

    # -- Optimization ----------------------------------------------------------
    - title: Optimization
      desc: Optimization declarations and runs.
      contents:
        - optimize.Optimization
        - optimize.OptimizationRun
        - optimize.capture_optimizations

    # -- Materials -------------------------------------------------------------
    - title: Materials
      desc: The Material class and the material catalogue.
      contents:
        - Material
        - materials.catalogue
        - materials.aluminium_6061
        - materials.copper_c11000
        - materials.steel_1018
        - materials.titanium_ti6al4v
        - materials.fr4
        - materials.silicon
        - materials.thermal_pad
        - materials.pla

    # -- Rendering -------------------------------------------------------------
    - title: Rendering and shader compilation
      desc: Forward raymarcher, construction overlay, WGSL compilation and the notebook viewer.
    - subtitle: Forward renderer
      desc: Scenes, cameras, settings and render functions.
      contents:
        - render.Scene
        - render.Camera
        - render.RenderSettings
        - render.render_scene
        - render.render_raymarched
        - render.raymarch
        - render.make_gradient_sky
    - subtitle: Construction overlay
      desc: Draw sketch planes and profiles over a render.
      contents:
        - render.project_points
        - render.draw_profile
        - render.draw_plane
    - subtitle: Shader compilation
      desc: Compile SDFs and scenes to WGSL.
      contents:
        - backends.compile_sdf_to_wgsl
        - backends.compile_scene_to_wgsl
        - backends.wgsl.compile_scene_with_uniforms
        - backends.wgsl.ShaderProgram
        - backends.wgsl.ShaderParameter
    - subtitle: Notebook viewer
      desc: WebGPU viewer widget for Jupyter.
      contents:
        - viewer.widget.SDFViewer

    # -- Plugins ---------------------------------------------------------------
    - title: Plugins and extension contracts
      desc: Plugin types, the plugin registry and the extension contracts.
    - subtitle: Plugins
      desc: Plugin classes and probe results.
      contents:
        - plugins.Plugin
        - plugins.PythonPlugin
        - plugins.TesseractPlugin
        - plugins.Capabilities
        - plugins.PluginProbe
        - plugins.PluginMismatch
        - plugins.PluginConfigError
        - plugins.Differentiable
    - subtitle: Registry and configuration
      desc: Plugin lookup and configuration.
      contents:
        - plugins.PluginRegistry
        - plugins.PluginSpec
        - plugins.registry
        - plugins.set_registry
        - plugins.get_plugin
        - plugins.plugin_for_kind
        - plugins.register_plugin
        - plugins.available_plugins
        - plugins.build_registry
        - plugins.builtin_specs
        - plugins.entry_point_specs
        - plugins.load_config
        - plugins.parse_config
        - plugins.config_path
        - plugins.runtime_scratch
        - plugins.scratch_root
    - subtitle: Extension contracts
      desc: Interfaces per plugin kind and their value types.
      contents:
        - plugins.NodeMap
        - plugins.FeatureEdges
        - plugins.BRepExtractor
        - plugins.StepExporter
        - plugins.Drag
        - plugins.OwnedNodes
        - plugins.EdgeSet
        - plugins.DragOutcome

    # -- Flow ------------------------------------------------------------------
    - title: Flow solver (prototype)
      desc: Brinkman-penalised lattice Boltzmann flow and energy solver.
    - subtitle: Domain and solve
      desc: Grid, solid fraction and steady solve.
      contents:
        - flow.FlowGrid
        - flow.solid_fraction
        - flow.sample_solid_fraction
        - flow.FlowConfig
        - flow.FlowResult
        - flow.solve
        - flow.convergence
        - flow.recommended_alpha_max
        - flow.SteadyOptions
        - flow.steady_populations
        - flow.iterate_to_steady
        - flow.unrolled_populations
        - flow.residual_history
    - subtitle: Flow studies
      desc: Conjugate heat-transfer studies and boundary regions.
      contents:
        - flow.FlowStudy
        - flow.FlowStudyResult
        - flow.Inlet
        - flow.Outlet
        - flow.Walls
        - flow.HeatSource
        - flow.HeldTemperature
        - flow.region_mask
    - subtitle: Energy equation
      desc: Steady energy equation.
      contents:
        - flow.EnergyConfig
        - flow.solve_temperature
        - flow.conductivity
    - subtitle: Objectives
      desc: Scalar objectives and output fields.
      contents:
        - flow.pressure_drop
        - flow.heat_transfer_proxy
        - flow.thermal_resistance
        - flow.peak_temperature
        - flow.mean_temperature
        - flow.bulk_outlet_temperature
        - flow.energy_imbalance
        - flow.fields
        - flow.pressure
    - subtitle: Lattice
      desc: Lattice Boltzmann primitives.
      contents:
        - flow.equilibrium
        - flow.macroscopic
        - flow.stream
        - flow.step
        - flow.step_for
        - flow.initial_populations
        - flow.bounce_back_mask
        - flow.duct_walls
        - flow.omega_from_viscosity
        - flow.viscosity_from_omega

    # -- Utilities -------------------------------------------------------------
    - title: Utilities
      desc: Compilation cache, option sets and tier availability.
    - subtitle: Compilation cache
      desc: Persistent JAX compilation cache.
      contents:
        - cache.enable_compilation_cache
        - cache.cache_directory
        - cache.prune_compilation_cache
        - cache.min_compile_seconds
    - subtitle: Option sets
      desc: String enums for option values, and parsing helpers.
      contents:
        - enums.Option
        - enums.MeshMethod
        - enums.TetMesher
        - enums.StudyKind
        - enums.BoundaryConditionType
        - enums.Side
        - enums.ObjectiveMetric
        - enums.OptimizerMethod
        - enums.OptimizationArgument
        - enums.GradientPath
        - enums.Precision
        - enums.ConstraintKind
        - enums.ConstraintSolveMethod
        - enums.ExportFormat
        - enums.FemBackend
        - enums.PluginKind
        - enums.PluginTransport
        - enums.values
        - enums.listed
        - enums.either
        - enums.parse
    - subtitle: Tier availability
      desc: Availability of private-tier plugin kinds.
      contents:
        - tier.status
        - tier.available
        - tier.require
        - tier.component
        - tier.message
        - tier.report
        - tier.absent
        - tier.TierUnavailable
        - tier.TierStatus
        - tier.KindStatus

    # -- Playground payload schema ---------------------------------------------
    - title: Playground payload schema (internal)
      desc: "Internal. JSON payloads between the compile worker and the playground frontend. Not a stable API."
      contents:
        - viewer.schema.CompilePayload
        - viewer.schema.ConstructionNode
        - viewer.schema.ConstructionElement
        - viewer.schema.ConstructionArgument
        - viewer.schema.ConstructionFace
        - viewer.schema.ConstructionPlane
        - viewer.schema.ConstructionVertex
        - viewer.schema.ConstructionConstraint
        - viewer.schema.ConstructionRelation
        - viewer.schema.ConstructionOperator
        - viewer.schema.ConstructionTransform
        - viewer.schema.ConstraintSolverRun
        - viewer.schema.PlaneReference
        - viewer.schema.FaceOwner
        - viewer.schema.DomainEntry
        - viewer.schema.IdentityEntry
        - viewer.schema.MaterialDefinition
        - viewer.schema.SimMeshPayload
        - viewer.schema.MeshEdgePayload
        - viewer.schema.StudyPayload
        - viewer.schema.StudySelection
        - viewer.schema.StudyBc
        - viewer.schema.OptimizationPayload
        - viewer.schema.PatchAddress
        - viewer.schema.PatchRequest
        - viewer.schema.PatchResponse
        - viewer.schema.ExportRequest
        - viewer.schema.validate_patch_request
        - viewer.schema.typescript_source