knowledge_base.json

[
  {
    "topic": "Radiance Philosophy: Visualization vs. Simulation",
    "content": "Radiance is a lighting visualization and simulation tool, not just a photorealistic renderer. Its primary goal is to generate images where calculated light levels quantitatively match actual physical conditions, making it a research and engineering instrument for predicting visible radiation distribution with verifiable accuracy. The core unit is spectral radiance (W⋅sr−1⋅m−2), from which all other photometric metrics like illuminance (lux) can be derived. The validity of a simulation depends entirely on the accuracy of its inputs, following the principle of 'garbage in, garbage out'."
  },
  {
    "topic": "How Radiance Defines Light Sources",
    "content": "In Radiance, light is an attribute of a surface, not an independent entity. There are no disembodied 'point lights'. To create a light source, you must first define a geometric object (e.g., a polygon or sphere) and then assign it a material property that makes it self-luminous. The object itself becomes the light source."
  },
  {
    "topic": "Radiance Ray-Tracing Algorithm",
    "content": "Radiance uses a light-backwards ray-tracing algorithm. Instead of tracing rays forward from light sources, it traces rays backward from the viewpoint (a virtual camera or measurement point). These rays bounce off surfaces based on their defined properties. When a ray path terminates at a light-emitting surface, its radiance contribution is calculated and added to the total value for the initial pixel or point. This process simulates both direct and indirect (diffuse interreflection) illumination."
  },
  {
    "topic": "Radiance Scene File (.rad) Structure",
    "content": "A .rad file is a human-readable plain text file that describes a 3D environment, including geometry, materials, and light sources. It supports four basic statement types:\n- Comments: Lines beginning with '#' are ignored.\n- Primitives: Core definitions for surfaces (polygons, spheres) and modifiers (materials, textures).\n- Aliases: Associates a new name with a previously defined primitive.\n- External Commands: Lines beginning with '!' are executed by the system shell, allowing for procedural geometry, file inclusion, and complex scene construction."
  },
  {
    "topic": "Radiance Universal Primitive Syntax",
    "content": "Every primitive in Radiance (materials, surfaces, etc.) follows a universal syntax:\n\nmodifier type identifier\nN S1 S2... SN\nI I1 I2... II\nM R1 R2... RM\n\n- modifier: The name of a previously defined primitive (like a material) that modifies the current one. Use 'void' for base materials.\n- type: A keyword specifying the primitive type (e.g., polygon, plastic, light).\n- identifier: A unique, user-defined name for the new primitive.\n- Argument Blocks: The next three lines contain string (N), integer (I), and real/floating-point (M) arguments, each preceded by a count of the arguments on that line."
  },
  {
    "topic": "Two-Step Principle of Creating a Light Source",
    "content": "Adding an artificial light source in Radiance is a two-step procedure:\n1. Define a Light Material: Create a material primitive using a light-emitting type (e.g., 'light', 'spotlight'). This defines the light's color and intensity and gives it a unique name.\n2. Apply the Material to Geometry: Create a geometric primitive (e.g., a polygon or sphere) and use the name of the light material from Step 1 as its modifier. This transforms the geometric object into a luminaire."
  },
  {
    "topic": "Example: Creating a Spherical Light Source",
    "content": "This example shows the two-step process for creating a spherical light source:\n\n```\n# Step 1: Define the light-emitting material.\n# The modifier is \"void\", type is \"light\", identifier is \"bright\".\nvoid light bright\n0\n0\n3  100  100  100  # R G B (Radiance in W/sr/m^2)\n\n# Step 2: Define geometry and apply the material.\n# The modifier is \"bright\", the material defined above.\n# The type is \"sphere\", the identifier is \"fixture\".\nbright sphere fixture\n0\n0\n4  2  1  1.5  0.125 # x_cen y_cen z_cen radius\n```"
  },
  {
    "topic": "Native Light Source Primitive: light",
    "content": "The 'light' primitive is the most fundamental light-emitting material. It models a surface as a perfect, uniform, diffuse emitter (Lambertian distribution), radiating light equally in all directions. It is ideal for bare lamps or simple luminous panels.\n\nSyntax:\nvoid light light_identifier\n0\n0\n3  Red_emission  Green_emission  Blue_emission\n\nThe three real arguments define the spectral radiance in W⋅sr−1⋅m−2 for the R, G, and B channels, controlling both color and intensity."
  },
  {
    "topic": "Native Light Source Primitive: spotlight",
    "content": "The 'spotlight' primitive models luminaires with directed output, like downlights or track lights. It defines color, intensity, direction, and angular spread.\n\nSyntax:\nvoid spotlight spotlight_identifier\n0\n0\n7  Red Green Blue  cone_angle  dx dy dz\n\n- Red, Green, Blue: Radiance in W⋅sr−1⋅m−2.\n- cone_angle: Full angular width of the emission cone in degrees (0-360).\n- dx, dy, dz: A 3D vector defining the beam's orientation."
  },
  {
    "topic": "spotlight: Direction Vector and Focal Length",
    "content": "The direction vector (dx dy dz) in a 'spotlight' primitive serves a dual purpose. Its orientation aims the light, but its magnitude (length) defines an effective focal length, simulating how a real lens or reflector collimates light. This changes the light falloff from the standard 1/r² to something closer to 1/(r+e)², where 'e' is the vector's magnitude. To simply aim the spotlight without this focusing effect, you must use a normalized direction vector (a vector with a length of 1.0), such as (0 0 -1) to aim straight down."
  },
  {
    "topic": "Native Light Source Primitive: glow",
    "content": "The 'glow' primitive is for self-luminous surfaces where the contribution to scene illumination can be precisely controlled or eliminated, making it an essential optimization tool. It is ideal for sources that must be visible but have negligible photometric impact, like indicator LEDs or exit signs.\n\nSyntax:\nvoid glow glow_identifier\n0\n0\n4  Red Green Blue  max_radius"
  },
  {
    "topic": "glow: The max_radius Parameter",
    "content": "The 'max_radius' parameter in a 'glow' material controls its participation in the lighting calculation:\n- If max_radius > 0: The surface acts as a light source, but only for objects within this specified radius.\n- If max_radius = 0 (default): The surface is visible and contributes to indirect (ambient) calculations, but never casts direct shadows.\n- If max_radius < 0: The surface is purely cosmetic. It is visible but completely excluded from all lighting calculations (direct and indirect). This is the most efficient option for things like indicator lights."
  },
  {
    "topic": "Native Light Source Primitive: illum",
    "content": "The 'illum' primitive is for modeling secondary light sources, like luminaire diffusers or windows. Its key feature is that it acts as a light source for calculations but adopts the appearance of a different, specified material when viewed directly. This provides a computationally efficient way to model things like translucent diffusers without modeling the lamp inside.\n\nSyntax:\nalternate_material illum illum_identifier\n0\n0\n3  Red Green Blue"
  },
  {
    "topic": "illum: Modeling Luminaire Diffusers",
    "content": "The expert workflow for modeling a luminaire with a diffuser uses the 'illum' primitive. Instead of modeling the fixture box and internal lamp, you only model the visible diffuser polygon. The process is:\n1. Define a standard material (e.g., 'trans' or 'plastic') that describes the visual appearance of the diffuser.\n2. Define an 'illum' material. Use the name of the appearance material from step 1 as its modifier. Set the RGB values to the desired light output of the fixture.\n3. Apply this 'illum' material to the diffuser polygon. This is more efficient because for the rest of the scene, the diffuser itself is the light source, but when viewed by the camera, it appears as the correct translucent material."
  },
  {
    "topic": "Summary of Light-Emitting Material Primitives",
    "content": "- light: General purpose diffuse emitter (bare bulb, luminous panel). Provides uniform, Lambertian emission.\n- spotlight: Directional luminaires (downlight, projector). Emits light within a defined cone; direction vector magnitude acts as a focal length.\n- glow: Computationally inexpensive sources (LEDs, screens). Contribution to scene illumination is controlled by `max_radius`, allowing for purely cosmetic sources.\n- illum: Secondary sources with a custom appearance (luminaire diffuser, luminous ceiling). Acts as a light source for calculations but appears as a different `alternate_material` when viewed directly."
  },
  {
    "topic": "Incorporating Photometric Data with ies2rad",
    "content": "Professional lighting design uses photometric data from manufacturers, typically in IES LM-63 format (.ies files). Radiance uses the 'ies2rad' command-line utility to translate this data into a Radiance scene description. It generates a .rad file containing the luminaire geometry and an 'illum' material, and a .dat file containing the interpolated photometric data that the 'illum' material references."
  },
  {
    "topic": "Key ies2rad Command-Line Options",
    "content": "- -o outname: Sets the root name for the output files.\n- -d units: Defines output dimensions ('m' for meters, 'f' for feet, etc.). Default is meters.\n- -m factor: Multiplies output by a factor. Used for applying a Light Loss Factor (LLF).\n- -c r g b: Sets a custom color. Used with -t default.\n- -t lamp: Specifies a lamp type to look up in lamp.tab. Using '-t default' forces the use of the -c color.\n- -p prefdir: Places output files into a subdirectory."
  },
  {
    "topic": "Workflow: Using an IES File",
    "content": "1. Acquire an .ies file from a manufacturer.\n2. Execute ies2rad in the terminal: `ies2rad downlight.ies`. This creates `downlight.rad` and `downlight.dat`.\n3. Integrate into your master scene file using the `!xform` command to place and orient the luminaire. Example: `!xform -t 1.5 2.0 2.8 -rx -90 downlight.rad`. This modular approach allows for easy placement of multiple instances."
  },
  {
    "topic": "Photometric Data Best Practices: Units",
    "content": "A mismatch between the units specified in the ies2rad command (-d flag) and the units used to model the main scene is one of the most common and catastrophic sources of error. If a scene is modeled in feet, but ies2rad is run with its default meter output, all lighting levels will be incorrect. It is imperative to ensure consistency."
  },
  {
    "topic": "Photometric Data Best Practices: Color",
    "content": "IES files do not contain spectral color information. For color consistency, the most robust practice is to override ies2rad's color inference. By using the `-t default` option along with `-c 1 1 1`, you can specify a color-balanced white light. Color temperature and chromaticity can then be adjusted globally in post-processing with the `pfilt` utility."
  },
  {
    "topic": "Geometric Primitives for Light Sources",
    "content": "A light-emitting material can be applied as a modifier to any standard geometric primitive to create a light source of a specific shape:\n- polygon: For flat, polygonal sources like troffers or linear fixtures.\n- sphere: For omnidirectional sources like bare lamps.\n- cylinder: For modeling linear fluorescent or LED tubes.\n- ring: For modeling the circular aperture of a recessed downlight."
  },
  {
    "topic": "Geometric Transformations with xform",
    "content": "`xform` is Radiance's utility for geometric transformations. Key options include:\n- -t x y z: Translate (Move).\n- -rx degrees: Rotate around the X-axis.\n- -ry degrees: Rotate around the Y-axis.\n- -rz degrees: Rotate around the Z-axis.\n- -s factor: Uniformly scale the object."
  },
  {
    "topic": "xform: Order of Operations",
    "content": "The order of transformation operations in `xform` is critical and non-commutative; they are applied sequentially. A common source of errors is incorrect ordering. The general rule of thumb is to perform scaling and rotation operations first, while the object is at the origin, and then perform the final translation to place it in the scene. For example, `!xform -rx 45 -t 5 0 0 object.rad` (rotate then translate) produces a different result than `!xform -t 5 0 0 -rx 45 object.rad` (translate then rotate)."
  },
  {
    "topic": "Creating Arrays of Luminaires with xform",
    "content": "`xform` can create arrays of objects efficiently using the `-a` (array) and `-i` (iterate) options.\n- `-a N`: Creates N copies of the input object. It works with the transform that immediately follows it, applying the transform cumulatively to each copy (0 times for the first, 1 time for the second, etc.).\n- `-i N`: Repeats the following transformation N times. It is often used to apply a global transformation to an entire array."
  },
  {
    "topic": "Best Practices for Scene File Management",
    "content": "For complex projects, it is best practice to use a modular file organization rather than a single monolithic .rad file. A typical project might be structured with separate files for materials (materials.rad), light definitions (lights.rad), and geometry (room_geom.rad). These components are then assembled in a master scene file using `!xform` and other commands. This approach makes scenes easier to manage, debug, and reuse."
  },
  {
    "topic": "Compiling a Scene with oconv",
    "content": "`oconv` is the Radiance scene compiler. It reads the textual .rad descriptions and builds a single binary file with a .oct extension. This octree is a spatial data structure that organizes the scene's geometry to make the ray-tracing process computationally feasible. Without this compilation step, rendering would be impossibly slow."
  },
  {
    "topic": "oconv: The Importance of Input File Order",
    "content": "A frequent source of errors is providing input files to `oconv` in the wrong order. A fundamental rule of Radiance is that a modifier must be defined before it is referenced. This means a file containing material definitions (e.g., materials.rad) must always be listed on the command line *before* any file containing geometry that uses those materials (e.g., room_geom.rad).\n- Correct: `oconv materials.rad room_geom.rad > scene.oct`\n- Incorrect: `oconv room_geom.rad materials.rad > scene.oct` (will cause an 'undefined modifier' error)."
  },
  {
    "topic": "Rendering an Image with rpict",
    "content": "`rpict` is the primary batch-mode rendering engine in Radiance. It takes a compiled .oct file and a set of parameters defining the view and calculation quality, and produces a high-dynamic-range (HDR) image. Key view parameters include:\n- -vp x y z: View point (camera location).\n- -vd dx dy dz: View direction (where the camera is pointing).\n- -vu ux uy uz: View up vector (defines 'up').\n- -vh angle / -vv angle: Horizontal and vertical field of view in degrees."
  },
  {
    "topic": "Troubleshooting: Noise and Splotches",
    "content": "The most common artifact in Radiance renderings is noise or splotchy patterns in indirectly lit areas. This is a direct result of insufficient sampling in the ambient calculation. The engine has not sent out enough rays to get a stable average of the incoming light. The solution is to increase the quality of the ambient calculation by raising the values of `-ad` (ambient divisions) and `-as` (ambient super-samples), which provides more samples to smooth out the result at the cost of longer render times."
  },
  {
    "topic": "Troubleshooting: Caustics and Specular Noise ('Fireflies')",
    "content": "Standard backward ray-tracing is inefficient at resolving focused specular reflections, like caustics from sunlight through glass or off a curved metal surface. Trying to solve this with `rpict` alone is often futile and results in extreme noise or 'fireflies'. For these cases, Radiance provides advanced tools like `mkillum` (a pre-calculation step for complex sources) or a full photon mapping extension, which is often the only viable method for cleanly rendering such scenes."
  },
  {
    "topic": "Radiance Engine in Modern GUI Tools",
    "content": "Many modern tools like ClimateStudio, Ladybug/Honeybee, and OpenStudio use Radiance as their simulation engine. These applications act as sophisticated wrappers, automatically generating .rad files and executing command-line programs like `oconv` and `rpict` behind the scenes. An understanding of the underlying Radiance principles is invaluable for troubleshooting unexpected results or extending the capabilities of these GUI-based tools."
  },
  {
    "topic": "Material: plastic",
    "content": "The 'plastic' material is for surfaces with uncolored specular highlights. It is defined by its RGB reflectance, its fraction of specularity, and its roughness value. Roughness is the RMS slope of surface facets, where 0 is perfectly smooth. Specularity fractions above 0.1 and roughness values above 0.2 are not very realistic.\n\nSyntax:\nvoid plastic id\n0\n0\n5 red green blue spec rough"
  },
  {
    "topic": "Material: metal",
    "content": "The 'metal' material is similar to plastic, but its specular highlights are modified by the material color. The specularity of metals is usually 0.9 or greater, and roughness values above 0.2 are uncommon.\n\nSyntax:\nvoid metal id\n0\n0\n5 red green blue spec rough"
  },
  {
    "topic": "Material: trans",
    "content": "'Trans' is a translucent material, similar to plastic but with added transmission properties. Transmissivity is the fraction of light that travels through the material. Transmitted specular is the fraction of transmitted light that is not diffusely scattered. Translucent objects are considered infinitely thin.\n\nSyntax:\nvoid trans id\n0\n0\n7 red green blue spec rough trans tspec"
  },
  {
    "topic": "Material: glass",
    "content": "The 'glass' material is optimized for thin glass surfaces (refractive index defaults to 1.52). It avoids modeling internal reflections by using a single surface. The primary specification is the transmissivity at normal incidence. To compute transmissivity (tn) from the more commonly measured transmittance (Tn), use the formula:\ntn = (sqrt(0.8402528435 + 0.0072522239*Tn*Tn) - 0.9166530661) / (0.0036261119*Tn)\n\nSyntax:\nvoid glass id\n0\n0\n3 rtn gtn btn"
  },
  {
    "topic": "Material: mirror",
    "content": "'Mirror' is for planar surfaces that produce virtual source reflections. It should be used sparingly as it can be computationally expensive. It is only supported for flat surfaces like polygons and rings. The arguments are the RGB reflectance values (0-1). An optional string argument can specify an alternate material for non-source rays, similar to 'illum'."
  },
  {
    "topic": "Material: BSDF",
    "content": "The 'BSDF' material type is used for complex fenestration systems. It references an XML file containing the Bidirectional Scattering Distribution Function data. The arguments include the thickness of the BSDF surface, the XML file path, and up, forward, and right-hand vectors.\n\nSyntax:\nvoid BSDF id\n6+ up_x up_y up_z fwd_x fwd_y fwd_z file.xml transform\n0\nN real_args..."
  },
  {
    "topic": "Material: antimatter",
    "content": "'Antimatter' is a material that can 'subtract' volumes from other volumes. A ray passing into an antimatter object becomes blind to all the specified modifiers. It does not work properly with the 'trans' material, and multiple antimatter surfaces should be disjoint. The viewpoint must be outside all concerned volumes for a correct rendering."
  },
  {
    "topic": "Material: mist",
    "content": "'Mist' is a virtual material used to delineate a volume of participating atmosphere, making light beams visible (e.g., from a spotlight). It can define an extinction coefficient, scattering albedo, and scattering eccentricity. It is often used to surround a beam from a spotlight or to model clouds."
  },
  {
    "topic": "Application Workflow: Project & Scene Setup",
    "content": "The user workflow begins with the left toolbar panels:\n1. Project Setup: Define project name, location (map or EPW file), and Radiance path.\n2. Dimensions: Set room width, length, height, and orientation.\n3. Apertures & Shading: Select walls in the 3D view to add windows and shading devices.\n4. Artificial Lighting & Materials: Configure surface properties and add light sources.\n5. Sensor Grid: Define points in space for simulation calculations."
  },
  {
    "topic": "Application Workflow: Simulation and Execution",
    "content": "After scene setup, the user configures the simulation using the right sidebar:\n1. Recipe Selection: Add simulation 'recipes' like 'Illuminance Map' or 'Annual Daylight'.\n2. Parameter Tuning: Configure settings for each recipe in its floating panel.\n3. Package Generation: The application gathers all data and generates a complete Radiance project folder with geometry (.rad), materials, and run scripts (.sh/.bat).\n4. Execution: In the Electron app, a 'Run Simulation' button executes the script. In a browser, the user downloads the package and runs it manually."
  },
  {
    "topic": "Application Workflow: Results and Analysis",
    "content": "The final stage involves analyzing the simulation output:\n1. Load Results: The user loads a result file (.ill, .hdr, .dgp) into the Analysis sidebar.\n2. Data Processing: A background web worker parses the file to prevent UI freezing, and the Results Manager calculates metrics (sDA, ASE, etc.).\n3. Visualization: Results are displayed as a false-color map on the 3D sensor grid and in specialized dashboards like the Annual Metrics Dashboard or HDR Image Viewer."
  },
  {
    "topic": "Application Architecture: UI Layer (ui.js)",
    "content": "`ui.js` is the central hub for user interaction. It caches DOM elements, manages all event listeners (sliders, buttons), controls the state of floating windows, updates UI labels, handles 3D scene interactions (wall/sensor clicks), and orchestrates the loading of result files and display of dashboards."
  },
  {
    "topic": "Application Architecture: 3D Visualization Layer (scene.js, geometry.js)",
    "content": "`scene.js` manages the Three.js environment, including the scene, cameras, renderer, and navigation controls. It contains the main `animate()` loop. `geometry.js` is responsible for creating and updating all 3D objects (room, windows, shading, sensor grids) based on parameters from the UI layer."
  },
  {
    "topic": "Application Architecture: State & Persistence (project.js)",
    "content": "The `Project` class in `project.js` is the single source of truth for the application's state. It gathers all settings into a comprehensive JSON object for saving, applies settings from a loaded project file, manages file system access, and orchestrates the generation of the final simulation package."
  },
  {
    "topic": "Application Architecture: Scripting Layer (scriptGenerator.js)",
    "content": "`scriptGenerator.js` is the core translation engine. It takes the consolidated project data object and generates the text content for all Radiance-compatible files, including geometry files (.rad), material files, and executable run scripts for different simulation recipes."
  },
  {
    "topic": "Application Architecture: Data Analysis Layer (resultsManager.js)",
    "content": "`resultsManager.js` is the engine for post-simulation analysis. It receives result files, offloads parsing to a web worker, stores all data (allowing for A/B comparison), calculates statistics and climate-based metrics (sDA, ASE, UDI), and provides methods for the UI to retrieve data for visualization."
  },
  {
    "topic": "Recommended Project Directory Structure",
    "content": "A well-organized project directory is critical for managing complexity. A recommended structure includes separate folders for different file types:\n- 01_geometry/: .rad files for scene geometry\n- 02_materials/: .mat or .rad files for materials\n- 04_skies/: .rad files for skies and .epw files\n- 06_octrees/: Compiled .oct files\n- 07_scripts/: BASH and Python scripts to run simulations\n- 08_results/: Raw numerical output (.ill, .dgp, .pts, etc.)\n- 09_images/: Final rendered images (.hdr, .png)"
  },
  {
    "topic": "Core Calculation Parameter: -ab (Ambient Bounces)",
    "content": "The `-ab` parameter specifies the maximum number of diffuse inter-reflections a ray will undergo. It controls the 'depth' of the indirect lighting simulation. A value of `-ab 0` disables indirect calculation. For most analyses, a value between 3 and 5 is a good balance of accuracy and speed. Higher values (6-7) are needed for complex geometries. A high `-ab` value is ineffective unless the ray weight limit (`-lw`) is set to a very small value."
  },
  {
    "topic": "Core Calculation Parameter: -ad (Ambient Divisions)",
    "content": "The `-ad` parameter sets the number of sample rays sent to probe the hemisphere for indirect illuminance. It is the primary control for resolving detail in indirect lighting. An insufficient `-ad` value is the most common cause of 'splotchy' or 'blotchy' artifacts in renderings. The first step in troubleshooting these artifacts is to increase the `-ad` value, often by doubling it."
  },
  {
    "topic": "Core Calculation Parameter: -as (Ambient Super-samples)",
    "content": "The `-as` parameter defines the number of additional samples used to refine the initial ambient divisions in areas where high variance is detected. After setting a reasonable base value for `-ad`, increasing `-as` can efficiently clean up remaining noise without the high cost of universally increasing `-ad`. A good starting point is to set `-as` to half the value of `-ad`."
  },
  {
    "topic": "Core Calculation Parameter: -aa (Ambient Accuracy)",
    "content": "The `-aa` parameter controls the allowable error for interpolation by the irradiance cache. It specifically manages *interpolation* error, not sampling error. Attempting to fix blotchy artifacts (an `-ad` problem) by lowering `-aa` is incorrect and will drastically increase computation time. A correct use for `-aa` is to resolve artifacts like smooth but incorrect gradients or light 'bleeding' around corners."
  },
  {
    "topic": "Core Calculation Parameter: -dj (Direct Jittering)",
    "content": "The `-dj` parameter introduces randomness to shadow rays for area light sources. A value of 0 produces sharp, unrealistic hard-edged shadows. A positive value (e.g., `-dj 0.7`) distributes shadow rays across the source, correctly simulating soft-edged shadows (penumbras). For direct sun analysis with `rcontrib`, it is often better to use `-dj 0` to ensure the ray is always sent to the center of the solar disc for consistency."
  },
  {
    "topic": "Recommended Ambient Parameter Quality Presets",
    "content": "- Draft/Preview: -ab 2 -ad 256 -as 128 -aa 0.25 (Fast, expects artifacts)\n- Standard/Good: -ab 4 -ad 1024 -as 512 -aa 0.2 (Balanced, good default)\n- High-Fidelity: -ab 7 -ad 4096 -as 2048 -aa 0.15 (For publication or complex scenes, slow)\n- Reference: -aa 0.0 (Disables interpolation, extremely slow, for research)"
  },
  {
    "topic": "Point-in-Time Workflow: Grid-Based Illuminance (rtrace)",
    "content": "This workflow calculates illuminance (lux) on a grid of sensor points. It uses the `rtrace` program with a sensor points file (.pts). Each line in the .pts file defines a sensor's location and orientation (X Y Z Vx Vy Vz). The `-I` switch is used to compute irradiance. The raw RGB output from `rtrace` is then converted to a single lux value using `rcalc` with the expression `'$1=179*($1*0.265+$2*0.670+$3*0.065)'`."
  },
  {
    "topic": "Point-in-Time Workflow: Daylight Factor (DF)",
    "content": "Daylight Factor (DF) is the ratio of interior illuminance to the available unobstructed exterior horizontal illuminance under a standard CIE Overcast Sky. The workflow involves using `gensky` with the `-c` flag for an overcast sky and the `-B` flag to set a reference horizontal irradiance (e.g., 55.866 W/m² to correspond to 10,000 lux). `rtrace` is used to find the interior illuminance, which is then divided by the reference value to get the DF percentage."
  },
  {
    "topic": "Point-in-Time Workflow: Daylight Glare Probability (DGP)",
    "content": "DGP analysis is a two-step process to assess visual discomfort. First, `rpict` is used to generate a high-quality 180° hemispherical fisheye HDR image (`-vth -vh 180 -vv 180`). Second, the `evalglare` program processes this image to calculate the DGP value. High-quality ambient parameters are essential for the `rpict` rendering, as an inaccurate background luminance will produce an incorrect DGP value."
  },
  {
    "topic": "DGP Interpretation Scale",
    "content": "The Daylight Glare Probability (DGP) value represents the fraction of people likely to be disturbed by glare. The scale is interpreted as follows:\n- DGP < 0.35: Imperceptible glare (Good)\n- 0.35 ≤ DGP < 0.40: Perceptible glare (Acceptable)\n- 0.40 ≤ DGP < 0.45: Disturbing glare (Poor)\n- DGP ≥ 0.45: Intolerable glare (Unacceptable)"
  },
  {
    "topic": "Annual Simulation: Daylight Coefficient (DC) Method",
    "content": "The Daylight Coefficient (DC) method is the foundation for annual simulations. It pre-calculates the relationship between a set of discrete sky patches and interior sensor points, storing this relationship in a Daylight Coefficient matrix (DC). The illuminance for any given sky condition can then be found with a simple matrix multiplication: E = DC * S, where S is the sky luminance vector. `rcontrib` is the primary tool for generating the DC matrix. The main limitation is inflexibility; if the glazing changes, the entire time-consuming calculation must be redone."
  },
  {
    "topic": "Annual Simulation: Three-Phase Method (3PM)",
    "content": "The Three-Phase Method (3PM) solves the inflexibility of the DC method by decoupling the light path into three matrices: V (View Matrix: window interior to sensor), T (Transmission Matrix: through the window, i.e., a BSDF file), and D (Daylight Matrix: sky to window exterior). The final illuminance is calculated by I = V * T * D * S. The great advantage is that different window systems (T matrices) can be tested rapidly without recalculating the V and D matrices, which are the most computationally intensive parts."
  },
  {
    "topic": "Annual Simulation: Five-Phase Method (5PM)",
    "content": "The Five-Phase Method (5PM) is the most accurate method for annual simulations where direct sunlight is critical (e.g., for calculating Annual Sunlight Exposure, ASE). It refines the 3PM by correcting for the 'smearing' of the sun's contribution across a large sky patch. It works by calculating the total 3PM result, subtracting the inaccurate direct-sun portion from the 3PM, and adding back a new, high-fidelity direct-sun portion calculated with a more accurate method. The equation is: I_5PM = I_3PM_total - I_3PM_direct + I_5PM_direct."
  },
  {
    "topic": "Annual Metrics: sDA, UDI, and ASE",
    "content": "After an annual simulation produces a raw .ill file, a post-processing script is used to calculate standard metrics:\n- sDA (Spatial Daylight Autonomy): A measure of sufficient daylight (e.g., % of area receiving at least 300 lux for 50% of occupied hours).\n- UDI (Useful Daylight Illuminance): Percentage of time a point is within a useful illuminance range (e.g., 100-2000 lux).\n- ASE (Annual Sunlight Exposure): A measure of excessive sunlight (% of area receiving at least 1000 lux of direct sun for 250 hours). ASE should be calculated using the 5-Phase Method."
  },
  {
    "topic": "Five-Phase Method: Prerequisites",
    "content": "To perform a five-phase simulation, you need a working Radiance installation, a Radiance model of the space (geometry and materials), a photocell points file (.pts) for sensor locations, an EPW weather file, and supporting calculation files like `klems_int.cal` and `reinhart.cal`."
  },
  {
    "topic": "Five-Phase Method: Required BSDFs",
    "content": "The five-phase method requires two different Bidirectional Scattering Distribution Functions (BSDFs) for the fenestration system:\n1. A tensor tree BSDF (e.g., fullwindow_t45.xml) for the accurate direct sun calculation (the Cds matrix).\n2. A Klems basis BSDF (e.g., fullwindow_klems.xml) for the standard three-phase components of the calculation. Both are typically generated using the `genBSDF` program."
  },
  {
    "topic": "Five-Phase Method Step 2: Calculating the standard 3-Phase term (I_3ph)",
    "content": "The first major calculation in the 5-phase method is to compute the standard three-phase result (I_3ph = V*T*D*S). This involves creating an octree for the scene (`oconv`), calculating the View Matrix (`rcontrib`), Daylight Matrix (`genklemsamp` | `rcontrib`), and Sky Matrix (`gendaymtx`), and then combining them with the Klems BSDF using `dctimestep`."
  },
  {
    "topic": "Five-Phase Method Step 3: Isolating the inaccurate 3-Phase direct sun term (I_ds-3ph)",
    "content": "To isolate the direct solar contribution from the standard 3-phase method, a special calculation is performed. This involves creating a 'black' octree where all scene surfaces are made non-reflective. Then, direct-only View (Vd) and Daylight (Dd) matrices are calculated using this black octree and modified ambient parameters (`-ab 1` or `-ab 0`). A direct-sun-only sky matrix (Sds) is generated using `gendaymtx -d`. These are combined with the Klems BSDF using `dctimestep`."
  },
  {
    "topic": "Five-Phase Method Step 4: Calculating the accurate direct sun term (I_ds-5ph)",
    "content": "To accurately calculate the direct solar contribution, a new high-resolution method is used. A `suns.rad` file with many (e.g., 5185) sun sources is created. A 'black' octree is generated that includes these suns and the high-resolution tensor tree BSDF. `rcontrib` is then run to create a Direct Sun Coefficient matrix (Cds). A special 5-phase sun matrix (Ssun) is created with `gendaymtx -5`. Finally, `dctimestep` combines the Cds and Ssun matrices."
  },
  {
    "topic": "Five-Phase Method Step 5: Combining Components for Final Result",
    "content": "The final 5-phase illuminance result is assembled by combining the three calculated terms using command-line tools like `rlam` and `rcalc`. The formula is applied to the output files from the previous steps: Final Result = (I_3ph) - (I_ds-3ph) + (I_ds-5ph). `rlam` pastes the records from the three files together, and `rcalc` performs the arithmetic on each channel (R, G, B) before converting the final result to lux."
  },
  {
    "topic": "Limitations of Tristimulus (RGB) Simulation for Non-Visual Effects",
    "content": "Standard RGB simulation is effective for visual rendering but discards significant spectral information. This is a problem for analyzing non-visual effects of light on human physiology, such as circadian rhythm synchronization, which is mediated by intrinsically photosensitive Retinal Ganglion Cells (ipRGCs). These cells contain melanopsin, which has a peak sensitivity in the blue region of the spectrum (~460-490 nm), different from the peak visual sensitivity (~555 nm). Therefore, a standard simulation cannot accurately predict these biological effects."
  },
  {
    "topic": "Spectral Analysis (9-Channel): N-Channel Methodology",
    "content": "The 9-channel spectral methodology overcomes the limitations of Radiance's 3-channel engine by running the simulation multiple times. The visible spectrum (380-780 nm) is partitioned into 'N' bins. The simulation is run N/3 times, with Radiance's R, G, and B channels repurposed in each run to represent three consecutive spectral bins. The results are then aggregated to reconstruct a full N-channel spectral result. This methodology uses a 9-channel approach, requiring 3 simulation runs."
  },
  {
    "topic": "Spectral Analysis (9-Channel): Wavelength Bins",
    "content": "The 9-channel simulation uses the following wavelength bins:\n- Channel 1: 380-424 nm\n- Channel 2: 425-454 nm\n- Channel 3: 455-479 nm\n- Channel 4: 480-504 nm\n- Channel 5: 505-529 nm\n- Channel 6: 530-559 nm\n- Channel 7: 560-599 nm\n- Channel 8: 600-644 nm\n- Channel 9: 645-780 nm"
  },
  {
    "topic": "Spectral Analysis (9-Channel): Pre-Processing Spectral Data",
    "content": "To prepare for a 9-channel spectral simulation, continuous spectral data (like an SPD for a light source or an SRD for a material) must be converted into a single representative value for each of the 9 channels. This is done by calculating the arithmetic mean of all spectral data points that fall within the defined wavelength range for each bin. This process results in a nine-element vector representing the binned spectral properties."
  },
  {
    "topic": "Spectral Analysis (9-Channel): Two-Pass Method for Sky/Sun Generation",
    "content": "To create a spectrally accurate yet energetically consistent sky model, Ray Modeler uses a 'two-pass' method with the `gendaylit` program. \nPass 1: `gendaylit` is run normally to get the correct baseline radiometric output (radiance) of a standard white sun.\nPass 2: A scaling coefficient is calculated to match the brightness of the custom binned solar spectrum to the baseline sun's brightness. `gendaylit` is then run again, but its output is programmatically modified (using `sed`) to apply the scaled binned colors to the sun and sky primitives."
  },
  {
    "topic": "Spectral Analysis (9-Channel): Post-Processing and Metric Calculation",
    "content": "The final stage transforms the raw 9-channel simulation output into meaningful metrics. The data from the three separate simulation runs is aggregated. Then, final metrics are calculated via a weighted sum, where the 9-channel spectral irradiance vector is multiplied by a vector of pre-calculated weighting coefficients specific to the desired metric (e.g., photopic, melanopic, neuropic)."
  },
  {
    "topic": "Spectral Analysis (9-Channel): Weighting Coefficients for Metrics",
    "content": "To calculate final metrics from the 9-channel spectral irradiance, the following weighting coefficients are used in a weighted sum:\n- Photopic Weights (V(λ)): [0.0003, 0.0232, 0.1465, 0.3644, 0.7386, 0.9859, 0.8654, 0.3804, 0.0535]\n- Melanopic Weights (S_mel(λ)): [0.0335, 0.4021, 0.7932, 0.8876, 0.6548, 0.3923, 0.1256, 0.0177, 0.0010]\n- Neuropic Weights (Neuropsin): [0.7259, 0.2312, 0.0000, 0.0000, 0.0000, 0.0000, 0.0000, 0.0000, 0.0000]"
  },
  {
    "topic": "Three-Phase Method: Core Concept",
    "content": "The Three-Phase Method is a powerful technique for analyzing complex fenestration systems. It calculates matrices representing each phase of light transport:\nD (Daylight Matrix): From the sky to the window exterior.\nT (Transmission Matrix): Through the window system (a BSDF file).\nV (View Matrix): From the window interior to the analysis points.\nS (Sky Matrix): The sky's luminance distribution.\nThe final illuminance is calculated by multiplying these matrices: i = V * T * D * S."
  },
  {
    "topic": "Three-Phase Method: Sky Generation (Phase 1)",
    "content": "This phase defines the luminous environment. For a single point in time, `gensky` is piped to `genskyvec` to create a sky vector (.skv). For an entire year, `epw2wea` converts a weather file to .wea format, which is then used by `gendaymtx` to generate an annual sky matrix (.smx) containing 8760 hourly sky vectors."
  },
  {
    "topic": "Three-Phase Method: Transmission Matrix / BSDF (Phase 2)",
    "content": "The Transmission Matrix (T) describes how light passes through the fenestration system. It is a Bidirectional Scattering Distribution Function (BSDF), typically generated as an .xml file using software like LBNL WINDOW. Inside the software, the user defines the glazing layers and shading systems and sets the angular basis to 'W6 standard basis' (Klems 145-patch basis) to generate the file."
  },
  {
    "topic": "Three-Phase Method: Daylight Matrix (Phase 3)",
    "content": "The Daylight Matrix (D) relates sky patches to incident light directions on the window exterior. It is generated using `rcontrib`. First, an octree of the building's exterior and any obstructions is created. Then, `genklemsamp` generates sampling rays from the window surface, which are piped to `rcontrib` to calculate the contribution coefficients from the sky patches, resulting in a .dmx file."
  },
  {
    "topic": "Three-Phase Method: View Matrix (Phase 4)",
    "content": "The View Matrix (V) characterizes how light leaving the window's interior surface contributes to sensor points. An octree of the room's interior is created where the window is modeled as a 'glow' light source. `rcontrib` is then used to trace rays from the sensor points (.pts file) back to this glowing window surface. The results are binned according to the Klems basis to match the BSDF, creating a .vmx file."
  },
  {

    "topic": "Three-Phase Method: Final Calculation (Phase 5)",
    "content": "The final results are calculated by multiplying the matrices using the `dctimestep` program. The command takes the V, T, D, and S matrices as input in that order. For an annual simulation, the `-n 8760` flag is used along with the annual sky matrix (.smx) to produce an annual results file (e.g., .ill)."
  },
  {

    "topic": "Radiance Calculation Strategy: Backward Ray-Tracing",
    "content": "The Radiance lighting simulation suite is a physically-based, backward ray-tracing engine renowned for its scientific accuracy. The term 'backward' refers to its computational strategy: instead of tracing millions of rays forward from light sources in the hope that some will enter the virtual camera, Radiance traces rays backward from each pixel of the virtual camera into the scene to determine what is visible. When a ray intersects a surface, the software calculates the light arriving at that point from all other sources in the environment. This approach is orders of magnitude more efficient for generating images and calculating values at specific points. Achieving accuracy is contingent upon a sophisticated understanding and correct application of its numerous calculation parameters."
  },
  {
    "topic": "The Ambient Calculation and Irradiance Cache",
    "content": "The majority of light within an architectural space arrives at a given point after reflecting off other surfaces. This indirect illumination is computationally intensive. Radiance employs a sophisticated algorithm known as the irradiance cache to manage this complexity efficiently. This cache is a form of adaptive sampling for global illumination. Instead of calculating the full hemispherical illumination at every single point, it computes it at select locations and then intelligently interpolates these values for nearby points, storing the results in an ambient file (.amb). The parameters that govern this process represent the most critical trade-offs between simulation speed and physical accuracy."
  },
  {
    "topic": "Core Calculation Parameter: -ar (Ambient Resolution)",
    "content": "The `-ar` parameter sets the density of the irradiance cache, effectively defining the maximum resolution for the indirect calculation relative to the overall scene size. It works in concert with `-aa`. The ambient resolution is divided by the scene's bounding box diagonal to determine the maximum density of cached values. This means the same `-ar` value will behave differently in a small room versus a large open-plan office. A very low `-aa` value (high accuracy) is of little use if `-ar` is also low, as the system will not have enough resolution to store the detailed ambient values it is being forced to calculate."
  },
  {
    "topic": "Core Calculation Parameter: -ds (Direct Sampling Ratio)",
    "content": "The `-ds` parameter controls the adaptive subdivision of large area light sources. It ensures that surfaces very close to a large source are sampled with sufficient detail to avoid artifacts, at a modest computational cost."
  },
  {
    "topic": "Core Calculation Parameter: -dt (Direct Thresholding)",
    "content": "The `-dt` parameter is an optimization that halts shadow testing for light sources whose potential contribution to a point falls below a specified fraction. In a scene with hundreds of lights, `-dt` allows Radiance to estimate the contribution of the farthest, least significant lights instead of tracing a shadow ray for every single one, saving time."
  },
  {
    "topic": "Core Calculation Parameter: -dc (Direct Certainty)",
    "content": "A value of 1 for the `-dc` parameter guarantees that all shadow lines resulting in a contrast change greater than the `-dt` value will be calculated explicitly. For high-accuracy simulations, especially those involving direct sunlight, it is standard practice to set `-dt 0` and `-dc 1`. This combination disables statistical approximation and forces a full, brute-force calculation for all light sources, ensuring maximum accuracy at the cost of longer simulation times."
  },
  {
    "topic": "Full Point-in-Time Illuminance Workflow (rtrace)",
    "content": "This workflow calculates illuminance (lux) on a grid of sensor points using the `rtrace` program. First, create a sensor points file (.pts) where each line defines a sensor's location and orientation (X Y Z Vx Vy Vz). For a horizontal work plane, the orientation vector is `0 0 1`. The core of the workflow is a single command pipeline that pipes the points file into `rtrace` and then pipes the `rtrace` output into `rcalc` for conversion to lux.\n\nExample shell script (`run_point_illuminance.sh`):\n```bash\n#!/bin/bash\n# --- Simulation Configuration ---\nPROJECT_NAME=\"office_test\"\nLATITUDE=34.05\nLONGITUDE=-118.24\nMERIDIAN=-120\nMONTH=6\nDAY=21\nTIME=14.5\n# Ambient Parameters (Standard Quality)\nAB=4\nAD=1024\nAS=512\nAR=512\nAA=0.2\n\n# --- File & Directory Setup ---\nGEOM_DIR=\"../01_geometry\"\nMAT_DIR=\"../02_materials\"\nSKY_DIR=\"../04_skies\"\nOCT_DIR=\"../06_octrees\"\nRESULTS_DIR=\"../08_results\"\n\nmkdir -p $SKY_DIR $OCT_DIR $RESULTS_DIR\n\n# 1. Generate Sky Description\nSKY_FILE=\"${SKY_DIR}/${PROJECT_NAME}_${MONTH}_${DAY}_${TIME}.rad\"\ngensky $MONTH $DAY $TIME -a $LATITUDE -o $LONGITUDE -m $MERIDIAN > $SKY_FILE\n\n# 2. Create Scene Octree\nOCTREE_FILE=\"${OCT_DIR}/${PROJECT_NAME}.oct\"\noconv ${MAT_DIR}/*.mat ${GEOM_DIR}/*.rad ${SKY_FILE} > $OCTREE_FILE\n\n# 3. Generate Analysis Grid (if it doesn't exist)\nPOINTS_FILE=\"${RESULTS_DIR}/grid.pts\"\nif [ ! -f \"$POINTS_FILE\" ]; then\n    gengrid 10 10 5 5 0.85 > $POINTS_FILE\nfi\n\n# 4. Run Illuminance Calculation\nRESULTS_FILE=\"${RESULTS_DIR}/${PROJECT_NAME}_illuminance.txt\"\nrtrace -I -h -w -ab $AB -ad $AD -as $AS -ar $AR -aa $AA $OCTREE_FILE < $POINTS_FILE | \\\nrcalc -e '$1=179*($1*0.265+$2*0.670+$3*0.065)' > $RESULTS_FILE\n\necho \"Simulation complete. Results in ${RESULTS_FILE}\"\n```"
  },
  {
    "topic": "Full Point-in-Time DGP Workflow (rpict & evalglare)",
    "content": "Daylight Glare Probability (DGP) analysis is a two-step process. First, `rpict` is used to generate a high-quality 180° hemispherical fisheye HDR image (`-vth -vh 180 -vv 180`). Second, the `evalglare` program processes this image to calculate the DGP value. High-quality ambient parameters are essential for the `rpict` rendering. The view is defined in a separate .vf file.\n\nExample view file (`glare_view.vf`):\n`rvu -vth -vp 2.5 1.5 1.2 -vd 0 1 0 -vu 0 0 1 -vh 180 -vv 180`\n\nExample shell script (`run_dgp_analysis.sh`):\n```bash\n#!/bin/bash\n# --- Simulation Configuration ---\nPROJECT_NAME=\"office_test\"\nLATITUDE=34.05\nLONGITUDE=-118.24\nMERIDIAN=-120\nMONTH=6\nDAY=21\nTIME=14.5\n# Ambient Parameters (High Quality is ESSENTIAL)\nAB=6\nAD=2048\nAS=1024\nAR=512\nAA=0.15\n\n# --- File & Directory Setup ---\nGEOM_DIR=\"../01_geometry\"\nMAT_DIR=\"../02_materials\"\nSKY_DIR=\"../04_skies\"\nOCT_DIR=\"../06_octrees\"\nVIEW_DIR=\"../03_views\"\nRESULTS_DIR=\"../08_results\"\nIMG_DIR=\"../09_images/hdr\"\nmkdir -p $SKY_DIR $OCT_DIR $RESULTS_DIR $IMG_DIR\n\n# 1. Generate Sky\nSKY_FILE=\"${SKY_DIR}/${PROJECT_NAME}_${MONTH}_${DAY}_${TIME}.rad\"\ngensky $MONTH $DAY $TIME -a $LATITUDE -o $LONGITUDE -m $MERIDIAN > $SKY_FILE\n\n# 2. Create Octree\nOCTREE_FILE=\"${OCT_DIR}/${PROJECT_NAME}.oct\"\noconv ${MAT_DIR}/*.mat ${GEOM_DIR}/*.rad ${SKY_FILE} > $OCTREE_FILE\n\n# 3. Render Fisheye Image\nVIEW_FILE=\"${VIEW_DIR}/glare_view.vf\"\nHDR_IMAGE=\"${IMG_DIR}/${PROJECT_NAME}_glare.hdr\"\nrpict -vf $VIEW_FILE -x 1500 -y 1500 \\\n      -ab $AB -ad $AD -as $AS -ar $AR -aa $AA \\\n      $OCTREE_FILE > $HDR_IMAGE\n\n# 4. Run evalglare\nGLARE_RESULTS=\"${RESULTS_DIR}/${PROJECT_NAME}_dgp.txt\"\nGLARE_CHECK_IMG=\"${IMG_DIR}/${PROJECT_NAME}_glare_check.hdr\"\nevalglare -d -c $GLARE_CHECK_IMG $HDR_IMAGE > $GLARE_RESULTS\n\necho \"Glare analysis complete. Results in ${GLARE_RESULTS}\"\n```"
  },
  {
    "topic": "Post-Processing Annual Metrics with Python",
    "content": "After running an annual simulation (e.g., with the Three-Phase Method), the raw .ill file contains 8760 illuminance values for every point. This data can be processed into meaningful metrics like sDA, UDI, and ASE using a Python script with the numpy and pandas libraries.\n\nExample script (`post_process_annual.py`):\n```python\nimport numpy as np\nimport pandas as pd\nimport argparse\nimport os\n\ndef calculate_metrics(illuminance_file: str, output_dir: str, num_points: int):\n    try:\n        data = np.fromfile(illuminance_file, dtype=np.float32)\n        annual_illuminance = data.reshape(8760, num_points)\n    except Exception as e:\n        print(f\"Error reading file: {e}\")\n        return\n\n    # Occupancy: Weekdays, 8 AM to 6 PM (17:00)\n    time_index = pd.to_datetime(pd.date_range(start='2023-01-01', periods=8760, freq='h'))\n    occupied_mask = (time_index.hour >= 8) & (time_index.hour <= 17) & (time_index.dayofweek < 5)\n    occupied_illuminance = annual_illuminance[occupied_mask, :]\n\n    # sDA (300 lux, 50% of hours)\n    sDA_points = np.sum(occupied_illuminance >= 300, axis=0) / occupied_illuminance.shape[0]\n    sDA = np.sum(sDA_points >= 0.5) / num_points * 100\n\n    # ASE (1000 lux, 250 hours) - requires 5-Phase method for accuracy\n    ASE_points = np.sum(occupied_illuminance >= 1000, axis=0)\n    ASE = np.sum(ASE_points >= 250) / num_points * 100\n\n    # UDI\n    udi_f = np.mean(occupied_illuminance < 100, axis=0) * 100\n    udi_s = np.mean((occupied_illuminance >= 100) & (occupied_illuminance < 500), axis=0) * 100\n    udi_a = np.mean((occupied_illuminance >= 500) & (occupied_illuminance < 2000), axis=0) * 100\n    udi_e = np.mean(occupied_illuminance >= 2000, axis=0) * 100\n\n    # Save results\n    summary = {'sDA_300_50%': [f\"{sDA:.2f}%\"], 'ASE_1000_250h': [f\"{ASE:.2f}%\"]}\n    summary_df = pd.DataFrame(summary)\n    summary_path = os.path.join(output_dir, \"annual_metrics_summary.csv\")\n    summary_df.to_csv(summary_path, index=False)\n    print(f\"Summary results saved to {summary_path}\")\n\nif __name__ == \"__main__\":\n    parser = argparse.ArgumentParser()\n    parser.add_argument(\"illuminance_file\", type=str)\n    parser.add_argument(\"--points\", type=int, required=True)\n    parser.add_argument(\"--outdir\", type=str, default=\"../08_results\")\n    args = parser.parse_args()\n    calculate_metrics(args.illuminance_file, args.outdir, args.points)\n```"
  },
  {
    "topic": "Troubleshooting Common Simulation Issues",
    "content": "Common simulation problems and their solutions:\n- **Light leaks at corners:** Caused by coincident surfaces. Ensure geometry is well-constructed with no gaps.\n- **Large, splotchy, or blotchy patches:** The `-ad` (Ambient Divisions) parameter is too low. Solution: Double the value of `-ad` and re-render. Do not try to fix this by lowering `-aa`.\n- **Smooth shadows with blocky boundaries:** The `-aa` (Ambient Accuracy) is too high or `-ar` (Ambient Resolution) is too low, causing poor interpolation. Solution: Decrease `-aa` and/or increase `-ar`.\n- **Scene appears too dark far from windows:** Insufficient light propagation. The `-ab` value is too low, or the `-lw` (limit weight) value is too high. Solution: Increase `-ab` to 5 or higher and decrease `-lw` to 1e-5 or lower.\n- **Incorrect DGP results:** Could be multiple causes: 1) Input image was not a 180° fisheye view. 2) Rendering quality was too low, giving inaccurate background luminance. 3) Wrong threshold method in `evalglare`. Solution: Verify `rpict` command used `-vth -vh 180 -vv 180`, re-render with High-Fidelity settings, and use the `-t` option in `evalglare`."
  },
  {

    "topic": "Radiance Program: dctimestep",
    "content": "`dctimestep` computes annual simulation results by multiplying pre-calculated matrices. It typically takes a View matrix, a Transmission matrix (BSDF), a Daylight matrix, and a Sky matrix as input. Key options:\n- `-n nsteps`: Specifies the number of time steps (e.g., 8760 for an annual simulation).\n- `-o ospec`: Specifies an output file or a pattern for multiple output files (e.g., for generating an image per time step)."
  },
  {
    "topic": "Radiance Program: epw2wea",
    "content": "`epw2wea` is a utility that transforms an EnergyPlus weather data file (.epw) into the DAYSIM weather file format (.wea). This converted format is then suitable for use with the `gendaymtx` program to create annual sky matrices."
  },
  {
    "topic": "Radiance Program: evalglare",
    "content": "`evalglare` evaluates glare sources within a 180-degree fisheye HDR image to calculate metrics like Daylight Glare Probability (DGP). Key options:\n- `-d`: Produces detailed output, listing properties of each detected glare source.\n- `-c fname`: Creates a 'check file,' which is a copy of the input image with detected glare sources highlighted in color for verification.\n- `-t xpos ypos angle`: Defines a task area on the image. This is the recommended method for determining the glare source threshold, which is based on the average luminance within this task area."
  },
  {
    "topic": "Radiance Program: genBSDF",
    "content": "`genBSDF` computes a bidirectional scattering distribution function (BSDF) from a Radiance scene description of a fenestration system. The output is an XML file conforming to the LBNL Window 6 standard. Key options:\n- `-c Nsamp`: Specifies the number of samples per incident direction (default 2000).\n- `-n Nproc`: Specifies the number of simultaneous processes to run.\n- `-t4 Nlog2`: Computes a non-uniform BSDF represented as a rank 4 tensor tree, suitable for high-accuracy direct sun calculations in the 5-Phase Method."
  },
  {
    "topic": "Radiance Program: gendaymtx",
    "content": "`gendaymtx` generates an annual Perez sky matrix (.smx) from a weather file (.wea). The output matrix contains luminance values for each sky patch for every hour of the year. Key options:\n- `-m N`: Increases sky resolution using Reinhart subdivision (e.g., `-m 1` for 146 patches, `-m 4` for 2306 patches).\n- `-d`: Produces a sun-only matrix with no sky contributions.\n- `-s`: Excludes the direct solar component.\n- `-5`: A special option used in the 5-Phase Method to generate a high-resolution direct sun matrix."
  },
  {
    "topic": "Radiance Program: gensky",
    "content": "`gensky` generates a Radiance scene description for the CIE standard sky distribution for a specific month, day, and time. Key options:\n- `-c`: Generates a cloudy (overcast) sky.\n- `+s`: Generates a sunny sky with the sun.\n- `-s`: Generates a sunny sky without the sun.\n- `-a lat -o lon -m mer`: Specifies site latitude, longitude, and standard meridian for accurate sun position.\n- `-B irrad`: Sets the zenith brightness based on a specified horizontal diffuse irradiance (in W/m²). Used in Daylight Factor workflows."
  },
  {
    "topic": "Radiance Program: pcomb",
    "content": "`pcomb` is used to combine Radiance pictures of equal size. It can perform linear combinations or more complex pixel-by-pixel operations defined by an expression. It is used in the image-based 5-Phase Method to combine the results from the different calculation phases using an expression like `-e 'ro=ri(1)-ri(2)+ri(3);...'`."
  },
  {
    "topic": "Radiance Program: rcontrib",
    "content": "`rcontrib` is a core program used to compute contribution coefficients, forming the basis of matrix-based methods. It traces rays from sensors and bins the results based on which source modifier (e.g., a sky patch) the ray terminates on. Key options:\n- `-I+`: Specifies that irradiance contributions should be calculated.\n- `-f file.cal`: A function file that defines how to map ray directions to bin numbers.\n- `-b var -bn N`: Specifies the bin variable and the total number of bins.\n- `-m modifier`: The base name of the modifier for which to calculate coefficients."
  },
  {
    "topic": "Radiance Program: rfluxmtx",
    "content": "`rfluxmtx` is a utility that acts as a wrapper for `rcontrib` to simplify the process of creating flux transfer matrices, such as the View (V) and Daylight (D) matrices in the Three-Phase Method. It samples rays uniformly over a sender surface and records their arrival at receiver surfaces."
  },
  {
    "topic": "Radiance Program: rmtxop",
    "content": "`rmtxop` performs matrix operations on files. It is used in annual simulation workflows to convert the RGB irradiance output from `dctimestep` into a single lux value. It can also be used to add and subtract matrices, which is essential for assembling the final result in the 5-Phase Method."
  },
  {
    "topic": "Radiance Program: vwrays",
    "content": "`vwrays` computes the ray origin and direction for each pixel of a specified view. Its output is typically piped directly into another program like `rtrace` or `rcontrib`. It is a key component in generating image-based View Matrices for the Three-Phase Method, where it generates the initial rays for a camera view that are then traced back to the window surface by `rcontrib`."
  },
  {
    "topic": "Core Parameter Deep Dive: -ab (Ambient Bounces)",
    "content": "The `-ab` parameter specifies the maximum number of diffuse inter-reflections a ray will undergo. It controls the 'depth' of the simulation. A value of `-ab 0` disables the indirect calculation entirely, useful for isolating direct solar contribution or for very fast previews. For most analyses, a value between 3 and 5 is a good balance of accuracy and speed. Higher values (6-7) are necessary for complex geometries like deep rooms or spaces with light shelves, where light must follow a tortuous path. A high `-ab` value is ineffective unless the ray weight limit (`-lw`) is set to a very small value (e.g., 1e-6) and the reflection limit (`-lr`) is also increased, otherwise rays will terminate prematurely."
  },
  {
    "topic": "Core Parameter Deep Dive: -ad (Ambient Divisions)",
    "content": "The `-ad` parameter sets the number of sample rays sent to probe the hemisphere for indirect illuminance and is the primary control for resolving detail in the first-bounce indirect lighting. An insufficient `-ad` value is the most common cause of 'splotchy' or 'blotchy' artifacts, which are a clear sign of undersampling the hemispherical environment. The scale of these splotches is much larger than a single pixel, indicating a fundamental issue with the ambient calculation. The first and most effective step in troubleshooting these artifacts is to increase the `-ad` value, often by doubling it."
  },
  {

    "topic": "Core Parameter Deep Dive: -as (Ambient Super-samples)",
    "content": "The `-as` parameter defines the number of additional samples used to refine the initial ambient divisions in areas where high variance is detected. It is a secondary, more targeted refinement. If the initial `-ad` samples show high variation (e.g., one hits a dark wall, the next a bright window), Radiance sends out `-as` extra samples to get a more accurate average]. After setting a reasonable base value for `-ad`, increasing `-as` can efficiently clean up remaining noise without the high cost of universally increasing `-ad`. A good starting point is to set `-as` to half the value of `-ad`."
  },
  {
    "topic": "Core Parameter Deep Dive: -aa (Ambient Accuracy)",
    "content": "The `-aa` parameter controls the allowable error for the interpolation performed by the irradiance cache. It specifically manages *interpolation* error, not sampling error. Attempting to fix blotchy artifacts (an `-ad` problem) by lowering `-aa` is incorrect and will drastically increase computation time. The correct use for `-aa` is to resolve artifacts that appear as smooth but incorrect gradients or light 'bleeding' around corners. A special value of `-aa 0` disables interpolation entirely, which is computationally prohibitive and reserved for generating reference results."
  },
  {
    "topic": "Core Parameter Deep Dive: -dj (Direct Jittering)",
    "content": "The `-dj` parameter introduces a random element to shadow rays for area light sources. A value of 0 produces sharp, unrealistic hard-edged shadows. A positive value (e.g., `-dj 0.7`) distributes shadow rays across the source, correctly simulating soft-edged shadows (penumbras). For direct sun analysis with `rcontrib`, it is often better to use `-dj 0` to ensure the ray is always sent to the center of the solar disc for maximum consistency."
  },
  {

    "topic": "rpict View Types (-vt)",
    "content": "Radiance supports several camera projection models using the `-vt` option:\n- **v (Perspective):** Standard rectilinear projection for realistic architectural visualization. \n- **l (Parallel):** Orthographic projection with no perspective, used for elevations, plans, and axonometric views. \n- **c (Cylindrical Panorama):** Creates 360° panoramic images. \n- **h (Hemispherical Fisheye):** Equidistant projection of a 180° hemisphere. Required for `evalglare` analysis. \n- **a (Angular Fisheye):** Distance from center is proportional to view angle. Also suitable for glare analysis. \n- **s (Planisphere):** Stereographic projection that preserves angles, used for sun-path diagrams."
  },
  {
    "topic": "Daylight Factor (DF) Workflow Steps",
    "content": "The Daylight Factor (DF) workflow calculates interior illuminance under a standard CIE Overcast Sky and normalizes the results. The steps are:\n1. **Create the Sky:** Use `gensky` with the `-c` flag for an overcast sky and the `-B` flag to set a reference horizontal irradiance. To get 10,000 lux, the command is `!gensky -c -B 55.866 > sky.rad` (since 10000 lux / 179 lm/W ≈ 55.866 W/m²). \n2. **Create Octree:** Combine the sky, geometry, and materials with `oconv`. \n3. **Calculate Interior Illuminance:** Use the standard `rtrace` workflow with the generated octree and a points file. A minimum of `-ab 3` is recommended for overcast conditions. \n4. **Calculate DF:** Use `rcalc` to process the raw irradiance. The expression converts the result to illuminance, divides by the 10,000 lux reference, and multiplies by 100 to get a percentage. \nExample rcalc command: `cat interior_irradiance.dat | rcalc -e '$1=100 * (179*($1*0.265+$2*0.670+$3*0.065)) / 10000' > results_df.txt`"
  },
  {
    "topic": "Three-Phase Method (3PM) Matrix Definitions",
    "content": "The Three-Phase Method (3PM) decouples the annual simulation light path into four distinct matrices, allowing for modular and rapid re-calculation. The governing equation is `I = V * T * D * S`. The matrices are:\n- **S (Sky Matrix):** A matrix of sky patch luminances for every time step in a year, generated from a climate file using `gendaymtx`. \n- **D (Daylight Matrix):** Describes light transport from the sky patches to the exterior surface of the fenestration. Calculated with `rcontrib`. \n- **T (Transmission Matrix):** Describes the optical behavior of the fenestration system itself. This is a Bidirectional Scattering Distribution Function (BSDF), typically an XML file generated by `genBSDF` or LBNL WINDOW. \n- **V (View Matrix):** Describes light transport from the interior surface of the fenestration to the final sensor points. Calculated with `rcontrib`."
  },
  {
    "topic": "Five-Phase Method (5PM) Correction Logic",
    "content": "The Five-Phase Method (5PM) refines the 3PM by performing a high-accuracy calculation for the direct sun component and using it to correct the base resultThis is critical for calculating Annual Sunlight Exposure (ASE) or analyzing light-redirecting systemsThe logic is to calculate three separate illuminance time-series and combine them.\nThe final equation is:\n`I_5PM = I_3PM_total - I_3PM_direct + I_5PM_direct`\nWhere:\n- `I_3PM_total` is the result from a standard 3-Phase simulation. \n- `I_3PM_direct` is the inaccurate direct-sun-only portion calculated using the 3PM. \n- `I_5PM_direct` is the new, high-fidelity direct-sun-only portion calculated with a more accurate method."
  },
  {
    "topic": "Five-Phase Method: Advanced Matrices (Vd, Dd, Cds)",
    "content": "The 5-Phase method introduces new matrices to isolate and accurately calculate the direct sun component:\n- **Vd and Dd (Direct-only View and Daylight Matrices):** These are generated using `rcontrib` with `-ab 0` (or `-ab 1`) and a special 'black' octree where all non-source surfaces are perfect absorbers. This ensures only the direct, un-reflected light paths are calculated for the subtraction step. \n- **Cds (Direct Sun Coefficient Matrix):** This is a new high-fidelity matrix that directly relates the sun's position to the interior sensors, bypassing the coarse sky patch discretization of the 3PM. It is calculated using `rcontrib` with an octree that contains many explicit sun sources (`suns.rad`) and a high-resolution tensor tree BSDF for the window. "
  },
  {

    "topic": "Radiance Program: rtrace (Detailed Options)",
    "content": "`rtrace` traces rays from standard input through a scene octree. Its behavior is controlled by numerous options, many of which are shared with `rpict`. Key options unique to or commonly used with `rtrace` include:\n- **-I (Uppercase i):** A boolean switch to compute irradiance instead of radiance, interpreting input as a measurement point and surface normal. This is essential for grid-based illuminance analysis. \n- **-h:** A switch to suppress the information header in the output file. \n- **-w:** A switch to suppress non-fatal warning messages. \n- **-ospec:** Produces output fields according to a specification string, allowing you to trace a ray's path and properties (e.g., `-ot` to trace, `-op` for intersection point, `-on` for normal). \n- **-n nproc:** Executes in parallel on `nproc` local processes to speed up calculation. \n- **-x res, -y res:** Sets the x and y resolution, which helps structure the output and is useful when creating image files from `rtrace` data. "
  },
  {
    "topic": "Radiance Program: rpict (Detailed Options)",
    "content": "`rpict` generates a 2D image from a scene octree. In addition to ambient parameters, its output is primarily controlled by view parameters:\n- **-vt[v|l|c|h|a|s]:** Sets the view type (e.g., `v` for perspective, `h` for hemispherical fisheye).\n- **-vp x y z:** Sets the View Point (camera location).\n- **-vd xd yd zd:** Sets the View Direction vector.\n- **-vu xu yu zu:** Sets the View Up vector, defining vertical orientation.\n- **-vh val / -vv val:** Sets the horizontal/vertical field of view in degrees (or width/height for parallel views).\n- **-x res / -y res:** Sets the horizontal/vertical resolution in pixels.\n- **-i:** A boolean switch to compute irradiance for each pixel instead of radiance."
  },
  {
    "topic": "Full 3-Phase Method Matrix Generation Script",
    "content": "This script generates the Daylight and View matrices, which is the most computationally intensive step of the 3-Phase Method and only needs to be run once for a given building geometry. High-quality ambient parameters are essential as they affect all subsequent results. \n\n**Filename:** `run_3ph_matrix_generation.sh` \n**Location:** `07_scripts/` \n```bash\n#!/bin/bash\n# --- Configuration ---\nPROJECT_NAME=\"office_3ph\"\n# Use high-quality parameters for matrix generation.\nAB=7\nAD=4096\nAS=2048\nAR=1024\nAA=0.1\n\n# --- File & Directory Setup ---\nGEOM_DIR=\"../01_geometry\"\nMAT_DIR=\"../02_materials\"\nOCT_DIR=\"../06_octrees\"\nRESULTS_DIR=\"../08_results\"\nmkdir -p $OCT_DIR $RESULTS_DIR\n\n# 1. Create Exterior Octree (for Daylight Matrix)\n# Contains only exterior geometry and windows with a placeholder material.\necho \"1. Creating EXTERIOR octree...\"\nEXT_OCTREE=\"${OCT_DIR}/${PROJECT_NAME}_exterior.oct\"\noconv -f ${MAT_DIR}/exterior_materials.mat ${GEOM_DIR}/exterior_geometry.rad > $EXT_OCTREE\n\n# 2. Generate Daylight Matrix (Sky -> Window Exterior)\necho \"2. Generating Daylight Matrix...\"\nDAYLIGHT_MTX=\"${RESULTS_DIR}/daylight.mtx\"\n# rcontrib calculates contribution from sky modifiers, binned into 145 Reinhart patches.\nrcontrib -I+ -w -ab $AB -ad $AD -as $AS -ar $AR -aa $AA \\\n         -f reinhart.cal -b tbin -bn 145 -m sky_glow \\\n         -c 10000 \\\n         $EXT_OCTREE < <(oconv -f -i $EXT_OCTREE ${GEOM_DIR}/windows.rad | xform -m window_surface) > $DAYLIGHT_MTX\nif [ $? -ne 0 ]; then echo \"Error generating Daylight Matrix. Exiting.\"; exit 1; fi\n\n# 3. Create Interior Octree (for View Matrix)\n# Contains only interior geometry. The window is the sole light source.\necho \"3. Creating INTERIOR octree...\"\nINT_OCTREE=\"${OCT_DIR}/${PROJECT_NAME}_interior.oct\"\noconv -f ${MAT_DIR}/interior_materials.mat ${GEOM_DIR}/interior_geometry.rad > $INT_OCTREE\n\n# 4. Generate View Matrix (Window Interior -> Sensors)\necho \"4. Generating View Matrix...\"\nVIEW_MTX=\"${RESULTS_DIR}/view.mtx\"\nPOINTS_FILE=\"${RESULTS_DIR}/grid.pts\" # Assumes this exists\n# Trace from sensor points back to the window, binning results by the Klems basis.\nrcontrib -I+ -w -ab $AB -ad $AD -as $AS -ar $AR -aa $AA \\\n         -f klems_int.cal -b kbin -bn 145 -m window_material \\\n         $INT_OCTREE < $POINTS_FILE > $VIEW_MTX\nif [ $? -ne 0 ]; then echo \"Error generating View Matrix. Exiting.\"; exit 1; fi\n\necho \"---\"\necho \"Matrix generation complete.\"\necho \"Daylight Matrix: ${DAYLIGHT_MTX}\"\necho \"View Matrix: ${VIEW_MTX}\"\necho \"---\"\n```"
  },
  {
    "topic": "Full 3-Phase Method Annual Calculation Script",
    "content": "This script performs the final, rapid calculation for a 3-Phase Method annual simulation. It takes the pre-calculated matrices, a weather file, and a window BSDF file to generate a year's worth of illuminance data. The key advantage is that you can test different window systems by simply swapping the BSDF file and re-running this fast script. \n\n**Filename:** `run_3ph_annual.sh` \n**Location:** `07_scripts/` \n```bash\n#!/bin/bash\n# --- Configuration ---\nPROJECT_NAME=\"office_3ph\"\n# Provide a path to an EnergyPlus Weather (EPW) file.\nWEATHER_FILE=\"/path/to/your/USA_CA_Los-Angeles.Intl.AP.722950_TMY3.epw\"\n\n# --- File & Directory Setup ---\nBSDF_DIR=\"../05_bsdf\"\nRESULTS_DIR=\"../08_results\"\n\n# 1. Generate Sky Matrix from Weather File\necho \"1. Generating sky matrix from EPW file...\"\nSKY_MTX=\"${RESULTS_DIR}/sky.smx\"\n# epw2wea converts EPW to WEA format, then gendaymtx creates the annual sky matrix.\nepw2wea $WEATHER_FILE | gendaymtx -m 1 > $SKY_MTX\nif [ $? -ne 0 ]; then echo \"Error generating Sky Matrix. Exiting.\"; exit 1; fi\n\n# 2. Run dctimestep to get annual results\necho \"2. Running dctimestep for annual simulation...\"\nDAYLIGHT_MTX=\"${RESULTS_DIR}/daylight.mtx\"\nVIEW_MTX=\"${RESULTS_DIR}/view.mtx\"\n# This is the modular part: swap this XML file to test a different window.\nBSDF_FILE=\"${BSDF_DIR}/clear_glass.xml\"\nANNUAL_RESULTS=\"${RESULTS_DIR}/${PROJECT_NAME}.ill\"\n\n# dctimestep performs the final matrix multiplication for all 8760 hours.\ndctimestep $VIEW_MTX $BSDF_FILE $DAYLIGHT_MTX $SKY_MTX > $ANNUAL_RESULTS\nif [ $? -ne 0 ]; then echo \"Error during dctimestep. Exiting.\"; exit 1; fi\n\necho \"---\"\necho \"Annual simulation complete.\"\necho \"Annual illuminance results saved to: ${ANNUAL_RESULTS}\"\necho \"You can now run the post-processing script on this file.\"\necho \"---\"\n```"
  },
  {
    "topic": "Detailed 5-Phase Method Workflow Commands",
    "content": "The 5-Phase Method provides high accuracy for direct sun by correcting a standard 3-Phase result. The core equation is `I_5ph = I_3ph - I_ds-3ph + I_ds-5ph`. This involves calculating three separate time-series of illuminance and combining them. \n\n**Part 1: Calculate Standard 3-Phase Term (`I_3ph`)**\n1.  **Generate V, D, S, and T matrices:** Follow the standard 3-Phase method. Use a Klems basis BSDF for the T matrix (e.g., `bsdf/fullwindow_klems.xml`). \n2.  **Run `dctimestep`:**\n    ```bash\n    dctimestep -n 8760 -if matrices/viewmatrix.vmx bsdf/fullwindow_klems.xml \\\n               matrices/daylightmatrix.dmx matrices/OakLand.smx | \\\n  rcollate -h -oc 1 > data/i_3ph.txt\n    ```\n    \n\n**Part 2: Calculate Inaccurate Direct 3-Phase Term (`I_ds-3ph`)**\n1.  [**Create 'black' octree:** Make all non-glazing surfaces non-reflective to isolate direct paths. \n    ```bash\n    xform -m black objects/testroom_Swall.rad objects/testroom.rad ... | \\\n      oconv materials/testroom.mat - ... > octs/model_allblack.oct\n    ```\n    \n2.  **Generate Direct View Matrix (`Vd`):** Use the black octree with `-ab 1`. \n    ```bash\n    rcontrib -I+ -ab 1 ... -m viewsurf octs/model_allblack.oct < data/photocells.pts > matrices/viewmatrix_direct.vmx\n    ```\n    \n3.  **Generate Direct Daylight Matrix (`Dd`):** Use the black octree with `-ab 0`. \n    ```bash\n    genklemsamp ... | rcontrib -c 1000 -ab 0 ... -m sky_glow octs/model_allblack.oct > matrices/daylightmatrix_direct.dmx\n    ```\n    \n4.  **Generate Direct Sun-Only Sky Matrix (`Sds`):** Use `gendaymtx` with the `-d` flag. \n    ```bash\n    gendaymtx -of -d skies/OakLand.wea > matrices/OakLand_direct.smx\n    ```\n    \n5.  **Run `dctimestep`:**\n    ```bash\n    dctimestep -n 8760 -if matrices/viewmatrix_direct.vmx bsdf/fullwindow_klems.xml \\\n               matrices/daylightmatrix_direct.dmx matrices/OakLand_direct.smx | \\\n               rcollate -h -oc 1 > data/i_ds3ph.txt\n    ```\n    \n\n**Part 3: Calculate Accurate Direct 5-Phase Term (`I_ds-5ph`)**\n1.  **Generate `suns.rad` file:** Create a scene file with many (e.g., 5185) sun sources. \n    ```bash\n    echo \"void light solar 0 0 3 1e6 1e6 1e6\" > skies/suns.rad\n    cnt 5185 | rcalc -e MF:6 -f reinsrc.cal -e Rbin=recno \\\n      -o 'solar source sun${Rbin} 0 0 4 ${Dx} ${Dy} ${Dz} 0.533' >> skies/suns.rad\n    ```\n    \n2.  **Generate Tensor Tree BSDF:** Create a high-resolution BSDF (e.g., `bsdf/fullwindow_t45.xml`) using `genBSDF`. \n3.  **Create suns octree:** Combine the black geometry, suns file, and the fenestration geometry using the high-resolution BSDF proxy. \n    ```bash\n    xform -m black ... | oconv materials/testroom.mat - ... objects/glazing_bsdf.rad skies/suns.rad > octs/model_suns.oct\n    ```\n    \n4.  **Generate Sun Coefficient Matrix (`Cds`):** Use `rcontrib` to relate sun positions to sensors via the high-res BSDF. \n    ```bash\n    rcontrib -I -ab 1 -ad 65536 -dc 1 -dt 0 -dj 0 ... -m solar \\\n             octs/model_suns.oct < data/photocells.pts > matrices/directsun.dsmx\n    ```\n    \n5. **Generate 5-Phase Sun Matrix (`Ssun`):** Use `gendaymtx` with the `-5` flag. \n    ```bash\n    gendaymtx -5 -d -m 6 -of skies/OakLand.wea > matrices/OakLand_direct_m6.smx\n    ```\n    \n6.  **Run `dctimestep`:**\n    ```bash\n    dctimestep -n 8760 -if matrices/directsun.dsmx matrices/OakLand_direct_m6.smx | \\\n               rcollate -h -oc 1 > data/i_ds5ph.txt\n    ```\n    \n\n**Part 4: Combine Final Results**\n1.  **Use `rlam` and `rcalc`:** Paste the three data files together and perform the final calculation, then convert to lux. \n    ```bash\n    rlam data/i_3ph.txt data/i_ds3ph.txt data/i_ds5ph.txt | \\\n      rcalc -e 'r=$1-$4+$7; g=$2-$5+$8; b=$3-$6+$9' \\\n            -e '$1=179*(.265*r+.670*g+.065*b)' | \\\n      rcollate -h -fa1 -ic 8760 -t > results/illum.txt\n    ```\n    "
  },
  {
    "topic": "Radiance Program Deep Dive: rcontrib",
    "content": "`rcontrib` is a core Radiance program that computes ray coefficients for objects identified by their modifiers. It is essential for matrix-based daylighting methods. \n\n**Key Functionality:**\n- Traces rays from an input source (e.g., sensor points) and tallies their contributions from specified light sources or sky patches (modifiers). \n- The output can be a contribution value (if `-V+` is used) or a coefficient that must be multiplied by the source's radiance (`-V-`, the default for daylight coefficients). \n\n**Important Settings:**\n- **`-n nprocs`**: Runs the calculation in parallel on `nprocs` processes to speed up computation. \n- **`-o ospec`**: Defines the output destination. Can be a file or a command pipe. `%s` is replaced by the modifier name and `%d` by the bin number. \n- **`-m mod`**: Specifies a modifier name (e.g., `sky_glow`) for which to compute contributions. Can be repeated. \n- **`-M file`**: Reads a list of modifier names from a file. \n- **`-b binv`**: Defines a 'bin number' expression, allowing for finer resolution, such as dividing a sky dome into patches. \n- **`-bn nbins`**: Specifies the total number of bins in advance, which is critical for correctly formatted output. \n- **`-f source`**: Reads definitions and expressions (e.g., for binning) from a source file, like `reinhart.cal` or `klems_int.cal`. \n- **`-c count`**: Accumulates and averages contributions over `count` input rays. A value of 0 produces a single record summing all input, useful for reverse sampling. \n- **`rtrace options`**: Accepts most standard `rtrace` options to control the quality of the ray-tracing (e.g., `-ab`, `-ad`, `-aa`, `-I+` for irradiance). "
  },
  {
    "topic": "Radiance Program Deep Dive: rmtxop",
    "content": "`rmtxop` loads and performs operations on matrix files. It is a critical utility for combining results in multi-phase simulations and for converting data formats. \n\n**Key Operations:**\n- **Concatenation (`.`):** Standard matrix multiplication. \n- **Addition (`+`):** Element-wise addition of two matrices. \n- **Element-wise Multiplication (`*`):** Multiplies corresponding elements of two matrices. \n- **Element-wise Division (`/`):** Divides elements of the first matrix by the second. \n\n**Important Settings:**\n- **`-v`**: Verbose mode, announces each operation. \n- **`-f[afdc]`**: Sets the output format: `a` for ASCII, `f` for float, `d` for double, `c` for RGBE color. \n- **`-t`**: Transposes the matrix, swapping rows and columns. Can be applied to inputs or the final result. \n- **`-s sf`**: Applies a scalar factor `sf` to the matrix elements. \n- **`-c c1 c2 ...`**: Transforms element values using coefficients. For example, `-c 47.4 119.9 11.6` converts a 3-component RGB irradiance matrix to a 1-component illuminance (lux) matrix. "
  },
  {
    "topic": "Radiance Philosophy: Visualization vs. Simulation",
    "content": "Radiance is a lighting visualization and simulation tool, not just a photorealistic renderer. Its primary goal is to generate images where calculated light levels quantitatively match actual physical conditions, making it a research and engineering instrument for predicting visible radiation distribution with verifiable accuracy. The core unit is spectral radiance (W⋅sr−1⋅m−2), from which all other photometric metrics like illuminance (lux) can be derived. The validity of a simulation depends entirely on the accuracy of its inputs, following the principle of 'garbage in, garbage out'."
  },
  {
    "topic": "How Radiance Defines Light Sources",
    "content": "In Radiance, light is an attribute of a surface, not an independent entity. There are no disembodied 'point lights'. To create a light source, you must first define a geometric object (e.g., a polygon or sphere) and then assign it a material property that makes it self-luminous. The object itself becomes the light source."
  },
  {
    "topic": "Radiance Ray-Tracing Algorithm",
    "content": "Radiance uses a light-backwards ray-tracing algorithm. Instead of tracing rays forward from light sources, it traces rays backward from the viewpoint (a virtual camera or measurement point). These rays bounce off surfaces based on their defined properties. When a ray path terminates at a light-emitting surface, its radiance contribution is calculated and added to the total value for the initial pixel or point. This process simulates both direct and indirect (diffuse interreflection) illumination."
  },
  {
    "topic": "Radiance Scene File (.rad) Structure",
    "content": "A .rad file is a human-readable plain text file that describes a 3D environment, including geometry, materials, and light sources. It supports four basic statement types:\n- Comments: Lines beginning with '#' are ignored.\n- Primitives: Core definitions for surfaces (polygons, spheres) and modifiers (materials, textures).\n- Aliases: Associates a new name with a previously defined primitive.\n- External Commands: Lines beginning with '!' are executed by the system shell, allowing for procedural geometry, file inclusion, and complex scene construction."
  },
  {
    "topic": "Radiance Universal Primitive Syntax",
    "content": "Every primitive in Radiance (materials, surfaces, etc.) follows a universal syntax:\n\nmodifier type identifier\nN S1 S2... SN\nI I1 I2... II\nM R1 R2... RM\n\n- modifier: The name of a previously defined primitive (like a material) that modifies the current one. Use 'void' for base materials.\n- type: A keyword specifying the primitive type (e.g., polygon, plastic, light).\n- identifier: A unique, user-defined name for the new primitive.\n- Argument Blocks: The next three lines contain string (N), integer (I), and real/floating-point (M) arguments, each preceded by a count of the arguments on that line."
  },
  {
    "topic": "Two-Step Principle of Creating a Light Source",
    "content": "Adding an artificial light source in Radiance is a two-step procedure:\n1. Define a Light Material: Create a material primitive using a light-emitting type (e.g., 'light', 'spotlight'). This defines the light's color and intensity and gives it a unique name.\n2. Apply the Material to Geometry: Create a geometric primitive (e.g., a polygon or sphere) and use the name of the light material from Step 1 as its modifier. This transforms the geometric object into a luminaire."
  },
  {
    "topic": "Example: Creating a Spherical Light Source",
    "content": "This example shows the two-step process for creating a spherical light source:\n\n```\n# Step 1: Define the light-emitting material.\n# The modifier is \"void\", type is \"light\", identifier is \"bright\".\nvoid light bright\n0\n0\n3  100  100  100  # R G B (Radiance in W/sr/m^2)\n\n# Step 2: Define geometry and apply the material.\n# The modifier is \"bright\", the material defined above.\n# The type is \"sphere\", the identifier is \"fixture\".\nbright sphere fixture\n0\n0\n4  2  1  1.5  0.125 # x_cen y_cen z_cen radius\n```"
  },
  {
    "topic": "Native Light Source Primitive: light",
    "content": "The 'light' primitive is the most fundamental light-emitting material. It models a surface as a perfect, uniform, diffuse emitter (Lambertian distribution), radiating light equally in all directions. It is ideal for bare lamps or simple luminous panels.\n\nSyntax:\nvoid light light_identifier\n0\n0\n3  Red_emission  Green_emission  Blue_emission\n\nThe three real arguments define the spectral radiance in W⋅sr−1⋅m−2 for the R, G, and B channels, controlling both color and intensity."
  },
  {
    "topic": "Native Light Source Primitive: spotlight",
    "content": "The 'spotlight' primitive models luminaires with directed output, like downlights or track lights. It defines color, intensity, direction, and angular spread.\n\nSyntax:\nvoid spotlight spotlight_identifier\n0\n0\n7  Red Green Blue  cone_angle  dx dy dz\n\n- Red, Green, Blue: Radiance in W⋅sr−1⋅m−2.\n- cone_angle: Full angular width of the emission cone in degrees (0-360).\n- dx, dy, dz: A 3D vector defining the beam's orientation."
  },
  {
    "topic": "spotlight: Direction Vector and Focal Length",
    "content": "The direction vector (dx dy dz) in a 'spotlight' primitive serves a dual purpose. Its orientation aims the light, but its magnitude (length) defines an effective focal length, simulating how a real lens or reflector collimates light. This changes the light falloff from the standard 1/r² to something closer to 1/(r+e)², where 'e' is the vector's magnitude. To simply aim the spotlight without this focusing effect, you must use a normalized direction vector (a vector with a length of 1.0), such as (0 0 -1) to aim straight down."
  },
  {
    "topic": "Native Light Source Primitive: glow",
    "content": "The 'glow' primitive is for self-luminous surfaces where the contribution to scene illumination can be precisely controlled or eliminated, making it an essential optimization tool. It is ideal for sources that must be visible but have negligible photometric impact, like indicator LEDs or exit signs.\n\nSyntax:\nvoid glow glow_identifier\n0\n0\n4  Red Green Blue  max_radius"
  },
  {
    "topic": "glow: The max_radius Parameter",
    "content": "The 'max_radius' parameter in a 'glow' material controls its participation in the lighting calculation:\n- If max_radius > 0: The surface acts as a light source, but only for objects within this specified radius.\n- If max_radius = 0 (default): The surface is visible and contributes to indirect (ambient) calculations, but never casts direct shadows.\n- If max_radius < 0: The surface is purely cosmetic. It is visible but completely excluded from all lighting calculations (direct and indirect). This is the most efficient option for things like indicator lights."
  },
  {
    "topic": "Native Light Source Primitive: illum",
    "content": "The 'illum' primitive is for modeling secondary light sources, like luminaire diffusers or windows. Its key feature is that it acts as a light source for calculations but adopts the appearance of a different, specified material when viewed directly. This provides a computationally efficient way to model things like translucent diffusers without modeling the lamp inside.\n\nSyntax:\nalternate_material illum illum_identifier\n0\n0\n3  Red Green Blue"
  },
  {
    "topic": "illum: Modeling Luminaire Diffusers",
    "content": "The expert workflow for modeling a luminaire with a diffuser uses the 'illum' primitive. Instead of modeling the fixture box and internal lamp, you only model the visible diffuser polygon. The process is:\n1. Define a standard material (e.g., 'trans' or 'plastic') that describes the visual appearance of the diffuser.\n2. Define an 'illum' material. Use the name of the appearance material from step 1 as its modifier. Set the RGB values to the desired light output of the fixture.\n3. Apply this 'illum' material to the diffuser polygon. This is more efficient because for the rest of the scene, the diffuser itself is the light source, but when viewed by the camera, it appears as the correct translucent material."
  },
  {
    "topic": "Summary of Light-Emitting Material Primitives",
    "content": "- light: General purpose diffuse emitter (bare bulb, luminous panel). Provides uniform, Lambertian emission.\n- spotlight: Directional luminaires (downlight, projector). Emits light within a defined cone; direction vector magnitude acts as a focal length.\n- glow: Computationally inexpensive sources (LEDs, screens). Contribution to scene illumination is controlled by `max_radius`, allowing for purely cosmetic sources.\n- illum: Secondary sources with a custom appearance (luminaire diffuser, luminous ceiling). Acts as a light source for calculations but appears as a different `alternate_material` when viewed directly."
  },
  {
    "topic": "Incorporating Photometric Data with ies2rad",
    "content": "Professional lighting design uses photometric data from manufacturers, typically in IES LM-63 format (.ies files). Radiance uses the 'ies2rad' command-line utility to translate this data into a Radiance scene description. It generates a .rad file containing the luminaire geometry and an 'illum' material, and a .dat file containing the interpolated photometric data that the 'illum' material references."
  },
  {
    "topic": "Key ies2rad Command-Line Options",
    "content": "- -o outname: Sets the root name for the output files.\n- -d units: Defines output dimensions ('m' for meters, 'f' for feet, etc.). Default is meters.\n- -m factor: Multiplies output by a factor. Used for applying a Light Loss Factor (LLF).\n- -c r g b: Sets a custom color. Used with -t default.\n- -t lamp: Specifies a lamp type to look up in lamp.tab. Using '-t default' forces the use of the -c color.\n- -p prefdir: Places output files into a subdirectory."
  },
  {
    "topic": "Workflow: Using an IES File",
    "content": "1. Acquire an .ies file from a manufacturer.\n2. Execute ies2rad in the terminal: `ies2rad downlight.ies`. This creates `downlight.rad` and `downlight.dat`.\n3. Integrate into your master scene file using the `!xform` command to place and orient the luminaire. Example: `!xform -t 1.5 2.0 2.8 -rx -90 downlight.rad`. This modular approach allows for easy placement of multiple instances."
  },
  {
    "topic": "Photometric Data Best Practices: Units",
    "content": "A mismatch between the units specified in the ies2rad command (-d flag) and the units used to model the main scene is one of the most common and catastrophic sources of error. If a scene is modeled in feet, but ies2rad is run with its default meter output, all lighting levels will be incorrect. It is imperative to ensure consistency."
  },
  {
    "topic": "Photometric Data Best Practices: Color",
    "content": "IES files do not contain spectral color information. For color consistency, the most robust practice is to override ies2rad's color inference. By using the `-t default` option along with `-c 1 1 1`, you can specify a color-balanced white light. Color temperature and chromaticity can then be adjusted globally in post-processing with the `pfilt` utility."
  },
  {
    "topic": "Geometric Primitives for Light Sources",
    "content": "A light-emitting material can be applied as a modifier to any standard geometric primitive to create a light source of a specific shape:\n- polygon: For flat, polygonal sources like troffers or linear fixtures.\n- sphere: For omnidirectional sources like bare lamps.\n- cylinder: For modeling linear fluorescent or LED tubes.\n- ring: For modeling the circular aperture of a recessed downlight."
  },
  {
    "topic": "Geometric Transformations with xform",
    "content": "`xform` is Radiance's utility for geometric transformations. Key options include:\n- -t x y z: Translate (Move).\n- -rx degrees: Rotate around the X-axis.\n- -ry degrees: Rotate around the Y-axis.\n- -rz degrees: Rotate around the Z-axis.\n- -s factor: Uniformly scale the object."
  },
  {
    "topic": "xform: Order of Operations",
    "content": "The order of transformation operations in `xform` is critical and non-commutative; they are applied sequentially. A common source of errors is incorrect ordering. The general rule of thumb is to perform scaling and rotation operations first, while the object is at the origin, and then perform the final translation to place it in the scene. For example, `!xform -rx 45 -t 5 0 0 object.rad` (rotate then translate) produces a different result than `!xform -t 5 0 0 -rx 45 object.rad` (translate then rotate)."
  },
  {
    "topic": "Creating Arrays of Luminaires with xform",
    "content": "`xform` can create arrays of objects efficiently using the `-a` (array) and `-i` (iterate) options.\n- `-a N`: Creates N copies of the input object. It works with the transform that immediately follows it, applying the transform cumulatively to each copy (0 times for the first, 1 time for the second, etc.).\n- `-i N`: Repeats the following transformation N times. It is often used to apply a global transformation to an entire array."
  },
  {
    "topic": "Best Practices for Scene File Management",
    "content": "For complex projects, it is best practice to use a modular file organization rather than a single monolithic .rad file. A typical project might be structured with separate files for materials (materials.rad), light definitions (lights.rad), and geometry (room_geom.rad). These components are then assembled in a master scene file using `!xform` and other commands. This approach makes scenes easier to manage, debug, and reuse."
  },
  {
    "topic": "Compiling a Scene with oconv",
    "content": "`oconv` is the Radiance scene compiler. It reads the textual .rad descriptions and builds a single binary file with a .oct extension. This octree is a spatial data structure that organizes the scene's geometry to make the ray-tracing process computationally feasible. Without this compilation step, rendering would be impossibly slow."
  },
  {
    "topic": "oconv: The Importance of Input File Order",
    "content": "A frequent source of errors is providing input files to `oconv` in the wrong order. A fundamental rule of Radiance is that a modifier must be defined before it is referenced. This means a file containing material definitions (e.g., materials.rad) must always be listed on the command line *before* any file containing geometry that uses those materials (e.g., room_geom.rad).\n- Correct: `oconv materials.rad room_geom.rad > scene.oct`\n- Incorrect: `oconv room_geom.rad materials.rad > scene.oct` (will cause an 'undefined modifier' error)."
  },
  {
    "topic": "Rendering an Image with rpict",
    "content": "`rpict` is the primary batch-mode rendering engine in Radiance. It takes a compiled .oct file and a set of parameters defining the view and calculation quality, and produces a high-dynamic-range (HDR) image. Key view parameters include:\n- -vp x y z: View point (camera location).\n- -vd dx dy dz: View direction (where the camera is pointing).\n- -vu ux uy uz: View up vector (defines 'up').\n- -vh angle / -vv angle: Horizontal and vertical field of view in degrees."
  },
  {
    "topic": "Troubleshooting: Noise and Splotches",
    "content": "The most common artifact in Radiance renderings is noise or splotchy patterns in indirectly lit areas. This is a direct result of insufficient sampling in the ambient calculation. The engine has not sent out enough rays to get a stable average of the incoming light. The solution is to increase the quality of the ambient calculation by raising the values of `-ad` (ambient divisions) and `-as` (ambient super-samples), which provides more samples to smooth out the result at the cost of longer render times."
  },
  {
    "topic": "Troubleshooting: Caustics and Specular Noise ('Fireflies')",
    "content": "Standard backward ray-tracing is inefficient at resolving focused specular reflections, like caustics from sunlight through glass or off a curved metal surface. Trying to solve this with `rpict` alone is often futile and results in extreme noise or 'fireflies'. For these cases, Radiance provides advanced tools like `mkillum` (a pre-calculation step for complex sources) or a full photon mapping extension, which is often the only viable method for cleanly rendering such scenes."
  },
  {
    "topic": "Radiance Engine in Modern GUI Tools",
    "content": "Many modern tools like ClimateStudio, Ladybug/Honeybee, and OpenStudio use Radiance as their simulation engine. These applications act as sophisticated wrappers, automatically generating .rad files and executing command-line programs like `oconv` and `rpict` behind the scenes. An understanding of the underlying Radiance principles is invaluable for troubleshooting unexpected results or extending the capabilities of these GUI-based tools."
  },
  {
    "topic": "Material: plastic",
    "content": "The 'plastic' material is for surfaces with uncolored specular highlights. It is defined by its RGB reflectance, its fraction of specularity, and its roughness value. Roughness is the RMS slope of surface facets, where 0 is perfectly smooth. Specularity fractions above 0.1 and roughness values above 0.2 are not very realistic.\n\nSyntax:\nvoid plastic id\n0\n0\n5 red green blue spec rough"
  },
  {
    "topic": "Material: metal",
    "content": "The 'metal' material is similar to plastic, but its specular highlights are modified by the material color. The specularity of metals is usually 0.9 or greater, and roughness values above 0.2 are uncommon.\n\nSyntax:\nvoid metal id\n0\n0\n5 red green blue spec rough"
  },
  {
    "topic": "Material: trans",
    "content": "'Trans' is a translucent material, similar to plastic but with added transmission properties. Transmissivity is the fraction of light that travels through the material. Transmitted specular is the fraction of transmitted light that is not diffusely scattered. Translucent objects are considered infinitely thin.\n\nSyntax:\nvoid trans id\n0\n0\n7 red green blue spec rough trans tspec"
  },
  {
    "topic": "Material: glass",
    "content": "The 'glass' material is optimized for thin glass surfaces (refractive index defaults to 1.52). It avoids modeling internal reflections by using a single surface. The primary specification is the transmissivity at normal incidence. To compute transmissivity (tn) from the more commonly measured transmittance (Tn), use the formula:\ntn = (sqrt(0.8402528435 + 0.0072522239*Tn*Tn) - 0.9166530661) / (0.0036261119*Tn)\n\nSyntax:\nvoid glass id\n0\n0\n3 rtn gtn btn"
  },
  {
    "topic": "Material: mirror",
    "content": "'Mirror' is for planar surfaces that produce virtual source reflections. It should be used sparingly as it can be computationally expensive. It is only supported for flat surfaces like polygons and rings. The arguments are the RGB reflectance values (0-1). An optional string argument can specify an alternate material for non-source rays, similar to 'illum'."
  },
  {
    "topic": "Material: BSDF",
    "content": "The 'BSDF' material type is used for complex fenestration systems. It references an XML file containing the Bidirectional Scattering Distribution Function data. The arguments include the thickness of the BSDF surface, the XML file path, and up, forward, and right-hand vectors.\n\nSyntax:\nvoid BSDF id\n6+ up_x up_y up_z fwd_x fwd_y fwd_z file.xml transform\n0\nN real_args..."
  },
  {
    "topic": "Material: antimatter",
    "content": "'Antimatter' is a material that can 'subtract' volumes from other volumes. A ray passing into an antimatter object becomes blind to all the specified modifiers. It does not work properly with the 'trans' material, and multiple antimatter surfaces should be disjoint. The viewpoint must be outside all concerned volumes for a correct rendering."
  },
  {
    "topic": "Material: mist",
    "content": "'Mist' is a virtual material used to delineate a volume of participating atmosphere, making light beams visible (e.g., from a spotlight). It can define an extinction coefficient, scattering albedo, and scattering eccentricity. It is often used to surround a beam from a spotlight or to model clouds."
  },
  {
    "topic": "Application Workflow: Project & Scene Setup",
    "content": "The user workflow begins with the left toolbar panels:\n1. Project Setup: Define project name, location (map or EPW file), and Radiance path.\n2. Dimensions: Set room width, length, height, and orientation.\n3. Apertures & Shading: Select walls in the 3D view to add windows and shading devices.\n4. Artificial Lighting & Materials: Configure surface properties and add light sources.\n5. Sensor Grid: Define points in space for simulation calculations."
  },
  {
    "topic": "Application Workflow: Simulation and Execution",
    "content": "After scene setup, the user configures the simulation using the right sidebar:\n1. Recipe Selection: Add simulation 'recipes' like 'Illuminance Map' or 'Annual Daylight'.\n2. Parameter Tuning: Configure settings for each recipe in its floating panel.\n3. Package Generation: The application gathers all data and generates a complete Radiance project folder with geometry (.rad), materials, and run scripts (.sh/.bat).\n4. Execution: In the Electron app, a 'Run Simulation' button executes the script. In a browser, the user downloads the package and runs it manually."
  },
  {
    "topic": "Application Workflow: Results and Analysis",
    "content": "The final stage involves analyzing the simulation output:\n1. Load Results: The user loads a result file (.ill, .hdr, .dgp) into the Analysis sidebar.\n2. Data Processing: A background web worker parses the file to prevent UI freezing, and the Results Manager calculates metrics (sDA, ASE, etc.).\n3. Visualization: Results are displayed as a false-color map on the 3D sensor grid and in specialized dashboards like the Annual Metrics Dashboard or HDR Image Viewer."
  },
  {
    "topic": "Application Architecture: UI Layer (ui.js)",
    "content": "`ui.js` is the central hub for user interaction. It caches DOM elements, manages all event listeners (sliders, buttons), controls the state of floating windows, updates UI labels, handles 3D scene interactions (wall/sensor clicks), and orchestrates the loading of result files and display of dashboards."
  },
  {
    "topic": "Application Architecture: 3D Visualization Layer (scene.js, geometry.js)",
    "content": "`scene.js` manages the Three.js environment, including the scene, cameras, renderer, and navigation controls. It contains the main `animate()` loop. `geometry.js` is responsible for creating and updating all 3D objects (room, windows, shading, sensor grids) based on parameters from the UI layer."
  },
  {
    "topic": "Application Architecture: State & Persistence (project.js)",
    "content": "The `Project` class in `project.js` is the single source of truth for the application's state. It gathers all settings into a comprehensive JSON object for saving, applies settings from a loaded project file, manages file system access, and orchestrates the generation of the final simulation package."
  },
  {
    "topic": "Application Architecture: Scripting Layer (scriptGenerator.js)",
    "content": "`scriptGenerator.js` is the core translation engine. It takes the consolidated project data object and generates the text content for all Radiance-compatible files, including geometry files (.rad), material files, and executable run scripts for different simulation recipes."
  },
  {
    "topic": "Application Architecture: Data Analysis Layer (resultsManager.js)",
    "content": "`resultsManager.js` is the engine for post-simulation analysis. It receives result files, offloads parsing to a web worker, stores all data (allowing for A/B comparison), calculates statistics and climate-based metrics (sDA, ASE, UDI), and provides methods for the UI to retrieve data for visualization."
  },
  {
    "topic": "Recommended Project Directory Structure",
    "content": "A well-organized project directory is critical for managing complexity. A recommended structure includes separate folders for different file types:\n- 01_geometry/: .rad files for scene geometry\n- 02_materials/: .mat or .rad files for materials\n- 04_skies/: .rad files for skies and .epw files\n- 06_octrees/: Compiled .oct files\n- 07_scripts/: BASH and Python scripts to run simulations\n- 08_results/: Raw numerical output (.ill, .dgp, .pts, etc.)\n- 09_images/: Final rendered images (.hdr, .png)"
  },
  {
    "topic": "Core Calculation Parameter: -ab (Ambient Bounces)",
    "content": "The `-ab` parameter specifies the maximum number of diffuse inter-reflections a ray will undergo. It controls the 'depth' of the indirect lighting simulation. A value of `-ab 0` disables indirect calculation. For most analyses, a value between 3 and 5 is a good balance of accuracy and speed. Higher values (6-7) are needed for complex geometries. A high `-ab` value is ineffective unless the ray weight limit (`-lw`) is set to a very small value."
  },
  {
    "topic": "Core Calculation Parameter: -ad (Ambient Divisions)",
    "content": "The `-ad` parameter sets the number of sample rays sent to probe the hemisphere for indirect illuminance. It is the primary control for resolving detail in indirect lighting. An insufficient `-ad` value is the most common cause of 'splotchy' or 'blotchy' artifacts in renderings. The first step in troubleshooting these artifacts is to increase the `-ad` value, often by doubling it."
  },
  {
    "topic": "Core Calculation Parameter: -as (Ambient Super-samples)",
    "content": "The `-as` parameter defines the number of additional samples used to refine the initial ambient divisions in areas where high variance is detected. After setting a reasonable base value for `-ad`, increasing `-as` can efficiently clean up remaining noise without the high cost of universally increasing `-ad`. A good starting point is to set `-as` to half the value of `-ad`."
  },
  {
    "topic": "Core Calculation Parameter: -aa (Ambient Accuracy)",
    "content": "The `-aa` parameter controls the allowable error for interpolation by the irradiance cache. It specifically manages *interpolation* error, not sampling error. Attempting to fix blotchy artifacts (an `-ad` problem) by lowering `-aa` is incorrect and will drastically increase computation time. A correct use for `-aa` is to resolve artifacts like smooth but incorrect gradients or light 'bleeding' around corners."
  },
  {
    "topic": "Core Calculation Parameter: -dj (Direct Jittering)",
    "content": "The `-dj` parameter introduces randomness to shadow rays for area light sources. A value of 0 produces sharp, unrealistic hard-edged shadows. A positive value (e.g., `-dj 0.7`) distributes shadow rays across the source, correctly simulating soft-edged shadows (penumbras). For direct sun analysis with `rcontrib`, it is often better to use `-dj 0` to ensure the ray is always sent to the center of the solar disc for consistency."
  },
  {
    "topic": "Recommended Ambient Parameter Quality Presets",
    "content": "- Draft/Preview: -ab 2 -ad 256 -as 128 -aa 0.25 (Fast, expects artifacts)\n- Standard/Good: -ab 4 -ad 1024 -as 512 -aa 0.2 (Balanced, good default)\n- High-Fidelity: -ab 7 -ad 4096 -as 2048 -aa 0.15 (For publication or complex scenes, slow)\n- Reference: -aa 0.0 (Disables interpolation, extremely slow, for research)"
  },
  {
    "topic": "Point-in-Time Workflow: Grid-Based Illuminance (rtrace)",
    "content": "This workflow calculates illuminance (lux) on a grid of sensor points. It uses the `rtrace` program with a sensor points file (.pts). Each line in the .pts file defines a sensor's location and orientation (X Y Z Vx Vy Vz). The `-I` switch is used to compute irradiance. The raw RGB output from `rtrace` is then converted to a single lux value using `rcalc` with the expression `'$1=179*($1*0.265+$2*0.670+$3*0.065)'`."
  },
  {
    "topic": "Point-in-Time Workflow: Daylight Factor (DF)",
    "content": "Daylight Factor (DF) is the ratio of interior illuminance to the available unobstructed exterior horizontal illuminance under a standard CIE Overcast Sky. The workflow involves using `gensky` with the `-c` flag for an overcast sky and the `-B` flag to set a reference horizontal irradiance (e.g., 55.866 W/m² to correspond to 10,000 lux). `rtrace` is used to find the interior illuminance, which is then divided by the reference value to get the DF percentage."
  },
  {

    "topic": "Point-in-Time Workflow: Daylight Glare Probability (DGP)",
    "content": "DGP analysis is a two-step process to assess visual discomfort. First, `rpict` is used to generate a high-quality 180° hemispherical fisheye HDR image (`-vth -vh 180 -vv 180`). Second, the `evalglare` program processes this image to calculate the DGP value. High-quality ambient parameters are essential for the `rpict` rendering, as an inaccurate background luminance will produce an incorrect DGP value."
  },
  {
    "topic": "DGP Interpretation Scale",
    "content": "The Daylight Glare Probability (DGP) value represents the fraction of people likely to be disturbed by glare. The scale is interpreted as follows:\n- DGP < 0.35: Imperceptible glare (Good)\n- 0.35 ≤ DGP < 0.40: Perceptible glare (Acceptable)\n- 0.40 ≤ DGP < 0.45: Disturbing glare (Poor)\n- DGP ≥ 0.45: Intolerable glare (Unacceptable)"
  },
  {
    "topic": "Annual Simulation: Daylight Coefficient (DC) Method",
    "content": "The Daylight Coefficient (DC) method is the foundation for annual simulations. It pre-calculates the relationship between a set of discrete sky patches and interior sensor points, storing this relationship in a Daylight Coefficient matrix (DC). The illuminance for any given sky condition can then be found with a simple matrix multiplication: E = DC * S, where S is the sky luminance vector. `rcontrib` is the primary tool for generating the DC matrix. The main limitation is inflexibility; if the glazing changes, the entire time-consuming calculation must be redone."
  },
  {

    "topic": "Annual Simulation: Three-Phase Method (3PM)",
    "content": "The Three-Phase Method (3PM) solves the inflexibility of the DC method by decoupling the light path into three matrices: V (View Matrix: window interior to sensor), T (Transmission Matrix: through the window, i.e., a BSDF file), and D (Daylight Matrix: sky to window exterior). The final illuminance is calculated by I = V * T * D * S. The great advantage is that different window systems (T matrices) can be tested rapidly without recalculating the V and D matrices, which are the most computationally intensive parts."
  },
  {
    "topic": "Annual Simulation: Five-Phase Method (5PM)",
    "content": "The Five-Phase Method (5PM) is the most accurate method for annual simulations where direct sunlight is critical (e.g., for calculating Annual Sunlight Exposure, ASE). It refines the 3PM by correcting for the 'smearing' of the sun's contribution across a large sky patch. It works by calculating the total 3PM result, subtracting the inaccurate direct-sun portion from the 3PM, and adding back a new, high-fidelity direct-sun portion calculated with a more accurate method. The equation is: I_5PM = I_3PM_total - I_3PM_direct + I_5PM_direct."
  },
  {
    "topic": "Annual Metrics: sDA, UDI, and ASE",
    "content": "After an annual simulation produces a raw .ill file, a post-processing script is used to calculate standard metrics:\n- sDA (Spatial Daylight Autonomy): A measure of sufficient daylight (e.g., % of area receiving at least 300 lux for 50% of occupied hours).\n- UDI (Useful Daylight Illuminance): Percentage of time a point is within a useful illuminance range (e.g., 100-2000 lux).\n- ASE (Annual Sunlight Exposure): A measure of excessive sunlight (% of area receiving at least 1000 lux of direct sun for 250 hours). ASE should be calculated using the 5-Phase Method."
  },
  {
    "topic": "Limitations of Tristimulus (RGB) Simulation for Non-Visual Effects",
    "content": "Standard RGB simulation is effective for visual rendering but discards significant spectral information. This is a problem for analyzing non-visual effects of light on human physiology, such as circadian rhythm synchronization, which is mediated by intrinsically photosensitive Retinal Ganglion Cells (ipRGCs). These cells contain melanopsin, which has a peak sensitivity in the blue region of the spectrum (~460-490 nm), different from the peak visual sensitivity (~555 nm). Therefore, a standard simulation cannot accurately predict these biological effects."
  },
  {
    "topic": "Spectral Analysis (9-Channel): N-Channel Methodology",
    "content": "The 9-channel spectral methodology overcomes the limitations of Radiance's 3-channel engine by running the simulation multiple times. The visible spectrum (380-780 nm) is partitioned into 'N' bins. The simulation is run N/3 times, with Radiance's R, G, and B channels repurposed in each run to represent three consecutive spectral bins. The results are then aggregated to reconstruct a full N-channel spectral result. This methodology uses a 9-channel approach, requiring 3 simulation runs."
  },
  {
    "topic": "Spectral Analysis (9-Channel): Wavelength Bins",
    "content": "The 9-channel simulation uses the following wavelength bins:\n- Channel 1: 380-424 nm\n- Channel 2: 425-454 nm\n- Channel 3: 455-479 nm\n- Channel 4: 480-504 nm\n- Channel 5: 505-529 nm\n- Channel 6: 530-559 nm\n- Channel 7: 560-599 nm\n- Channel 8: 600-644 nm\n- Channel 9: 645-780 nm"
  },
  {
    "topic": "Spectral Analysis (9-Channel): Pre-Processing Spectral Data",
    "content": "To prepare for a 9-channel spectral simulation, continuous spectral data (like an SPD for a light source or an SRD for a material) must be converted into a single representative value for each of the 9 channels. This is done by calculating the arithmetic mean of all spectral data points that fall within the defined wavelength range for each bin. This process results in a nine-element vector representing the binned spectral properties."
  },
  {
    "topic": "Spectral Analysis (9-Channel): Two-Pass Method for Sky/Sun Generation",
    "content": "To create a spectrally accurate yet energetically consistent sky model, Ray Modeler uses a 'two-pass' method with the `gendaylit` program. \nPass 1: `gendaylit` is run normally to get the correct baseline radiometric output (radiance) of a standard white sun.\nPass 2: A scaling coefficient is calculated to match the brightness of the custom binned solar spectrum to the baseline sun's brightness. `gendaylit` is then run again, but its output is programmatically modified (using `sed`) to apply the scaled binned colors to the sun and sky primitives."
  },
  {
    "topic": "Spectral Analysis (9-Channel): Post-Processing and Metric Calculation",
    "content": "The final stage transforms the raw 9-channel simulation output into meaningful metrics. The data from the three separate simulation runs is aggregated. Then, final metrics are calculated via a weighted sum, where the 9-channel spectral irradiance vector is multiplied by a vector of pre-calculated weighting coefficients specific to the desired metric (e.g., photopic, melanopic, neuropic)."
  },
  {
    "topic": "Spectral Analysis (9-Channel): Weighting Coefficients for Metrics",
    "content": "To calculate final metrics from the 9-channel spectral irradiance, the following weighting coefficients are used in a weighted sum:\n- Photopic Weights (V(λ)): [0.0003, 0.0232, 0.1465, 0.3644, 0.7386, 0.9859, 0.8654, 0.3804, 0.0535]\n- Melanopic Weights (S_mel(λ)): [0.0335, 0.4021, 0.7932, 0.8876, 0.6548, 0.3923, 0.1256, 0.0177, 0.0010]\n- Neuropic Weights (Neuropsin): [0.7259, 0.2312, 0.0000, 0.0000, 0.0000, 0.0000, 0.0000, 0.0000, 0.0000]"
  },
    {
    "topic": "Three-Phase Method: Core Concept",
    "content": "The Three-Phase Method is a powerful technique for analyzing complex fenestration systems. It calculates matrices representing each phase of light transport:\nD (Daylight Matrix): From the sky to the window exterior.\nT (Transmission Matrix): Through the window system (a BSDF file).\nV (View Matrix): From the window interior to the analysis points.\nS (Sky Matrix): The sky's luminance distribution.\nThe final illuminance is calculated by multiplying these matrices: i = V * T * D * S."
  },
    {
    "topic": "Three-Phase Method: Sky Generation (Phase 1)",
    "content": "This phase defines the luminous environment. For a single point in time, `gensky` is piped to `genskyvec` to create a sky vector (.skv). For an entire year, `epw2wea` converts a weather file to .wea format, which is then used by `gendaymtx` to generate an annual sky matrix (.smx) containing 8760 hourly sky vectors."
  },
{
    "topic": "Three-Phase Method: Transmission Matrix / BSDF (Phase 2)",
    "content": "The Transmission Matrix (T) describes how light passes through the fenestration system. It is a Bidirectional Scattering Distribution Function (BSDF), typically generated as an .xml file using software like LBNL WINDOW. Inside the software, the user defines the glazing layers and shading systems and sets the angular basis to 'W6 standard basis' (Klems 145-patch basis) to generate the file."
  },
    {
    "topic": "Three-Phase Method: Daylight Matrix (Phase 3)",
    "content": "The Daylight Matrix (D) relates sky patches to incident light directions on the window exterior. It is generated using `rcontrib`. First, an octree of the building's exterior and any obstructions is created. Then, `genklemsamp` generates sampling rays from the window surface, which are piped to `rcontrib` to calculate the contribution coefficients from the sky patches, resulting in a .dmx file."
  },
{
    "topic": "Three-Phase Method: View Matrix (Phase 4)",
    "content": "The View Matrix (V) characterizes how light leaving the window's interior surface contributes to sensor points. An octree of the room's interior is created where the window is modeled as a 'glow' light source. `rcontrib` is then used to trace rays from the sensor points (.pts file) back to this glowing window surface. The results are binned according to the Klems basis to match the BSDF, creating a .vmx file."
  },
{
    "topic": "Three-Phase Method: Final Calculation (Phase 5)",
    "content": "The final results are calculated by multiplying the matrices using the `dctimestep` program. The command takes the V, T, D, and S matrices as input in that order. For an annual simulation, the `-n 8760` flag is used along with the annual sky matrix (.smx) to produce an annual results file (e.g., .ill)."
  },
  {
    "topic": "Radiance Calculation Strategy: Backward Ray-Tracing",
    "content": "The Radiance lighting simulation suite is a physically-based, backward ray-tracing engine renowned for its scientific accuracy. The term 'backward' refers to its computational strategy: instead of tracing millions of rays forward from light sources in the hope that some will enter the virtual camera, Radiance traces rays backward from each pixel of the virtual camera into the scene to determine what is visible. When a ray intersects a surface, the software calculates the light arriving at that point from all other sources in the environment. This approach is orders of magnitude more efficient for generating images and calculating values at specific points. Achieving accuracy is contingent upon a sophisticated understanding and correct application of its numerous calculation parameters."
  },
  {
    "topic": "The Ambient Calculation and Irradiance Cache",
    "content": "The majority of light within an architectural space arrives at a given point after reflecting off other surfaces. This indirect illumination is computationally intensive. Radiance employs a sophisticated algorithm known as the irradiance cache to manage this complexity efficiently. This cache is a form of adaptive sampling for global illumination. Instead of calculating the full hemispherical illumination at every single point, it computes it at select locations and then intelligently interpolates these values for nearby points, storing the results in an ambient file (.amb). The parameters that govern this process represent the most critical trade-offs between simulation speed and physical accuracy."
  },
  {
    "topic": "Core Calculation Parameter: -ar (Ambient Resolution)",
    "content": "The `-ar` parameter sets the density of the irradiance cache, effectively defining the maximum resolution for the indirect calculation relative to the overall scene size. It works in concert with `-aa`. The ambient resolution is divided by the scene's bounding box diagonal to determine the maximum density of cached values. This means the same `-ar` value will behave differently in a small room versus a large open-plan office. A very low `-aa` value (high accuracy) is of little use if `-ar` is also low, as the system will not have enough resolution to store the detailed ambient values it is being forced to calculate."
  },
  {
    "topic": "Core Calculation Parameter: -ds (Direct Sampling Ratio)",
    "content": "The `-ds` parameter controls the adaptive subdivision of large area light sources. It ensures that surfaces very close to a large source are sampled with sufficient detail to avoid artifacts, at a modest computational cost."
  },
  {
    "topic": "Core Calculation Parameter: -dt (Direct Thresholding)",
    "content": "The `-dt` parameter is an optimization that halts shadow testing for light sources whose potential contribution to a point falls below a specified fraction. In a scene with hundreds of lights, `-dt` allows Radiance to estimate the contribution of the farthest, least significant lights instead of tracing a shadow ray for every single one, saving time."
  },
  {
    "topic": "Core Calculation Parameter: -dc (Direct Certainty)",
    "content": "A value of 1 for the `-dc` parameter guarantees that all shadow lines resulting in a contrast change greater than the `-dt` value will be calculated explicitly. For high-accuracy simulations, especially those involving direct sunlight, it is standard practice to set `-dt 0` and `-dc 1`. This combination disables statistical approximation and forces a full, brute-force calculation for all light sources, ensuring maximum accuracy at the cost of longer simulation times."
  },
  {
    "topic": "Full Point-in-Time Illuminance Workflow (rtrace)",
    "content": "This workflow calculates illuminance (lux) on a grid of sensor points using the `rtrace` program. First, create a sensor points file (.pts) where each line defines a sensor's location and orientation (X Y Z Vx Vy Vz). For a horizontal work plane, the orientation vector is `0 0 1`. The core of the workflow is a single command pipeline that pipes the points file into `rtrace` and then pipes the `rtrace` output into `rcalc` for conversion to lux.\n\nExample shell script (`run_point_illuminance.sh`):\n```bash\n#!/bin/bash\n# --- Simulation Configuration ---\nPROJECT_NAME=\"office_test\"\nLATITUDE=34.05\nLONGITUDE=-118.24\nMERIDIAN=-120\nMONTH=6\nDAY=21\nTIME=14.5\n# Ambient Parameters (Standard Quality)\nAB=4\nAD=1024\nAS=512\nAR=512\nAA=0.2\n\n# --- File & Directory Setup ---\nGEOM_DIR=\"../01_geometry\"\nMAT_DIR=\"../02_materials\"\nSKY_DIR=\"../04_skies\"\nOCT_DIR=\"../06_octrees\"\nRESULTS_DIR=\"../08_results\"\n\nmkdir -p $SKY_DIR $OCT_DIR $RESULTS_DIR\n\n# 1. Generate Sky Description\nSKY_FILE=\"${SKY_DIR}/${PROJECT_NAME}_${MONTH}_${DAY}_${TIME}.rad\"\ngensky $MONTH $DAY $TIME -a $LATITUDE -o $LONGITUDE -m $MERIDIAN > $SKY_FILE\n\n# 2. Create Scene Octree\nOCTREE_FILE=\"${OCT_DIR}/${PROJECT_NAME}.oct\"\noconv ${MAT_DIR}/*.mat ${GEOM_DIR}/*.rad ${SKY_FILE} > $OCTREE_FILE\n\n# 3. Generate Analysis Grid (if it doesn't exist)\nPOINTS_FILE=\"${RESULTS_DIR}/grid.pts\"\nif [ ! -f \"$POINTS_FILE\" ]; then\n    gengrid 10 10 5 5 0.85 > $POINTS_FILE\nfi\n\n# 4. Run Illuminance Calculation\nRESULTS_FILE=\"${RESULTS_DIR}/${PROJECT_NAME}_illuminance.txt\"\nrtrace -I -h -w -ab $AB -ad $AD -as $AS -ar $AR -aa $AA $OCTREE_FILE < $POINTS_FILE | \\\nrcalc -e '$1=179*($1*0.265+$2*0.670+$3*0.065)' > $RESULTS_FILE\n\necho \"Simulation complete. Results in ${RESULTS_FILE}\"\n```"
  },
  {
    "topic": "Full Point-in-Time DGP Workflow (rpict & evalglare)",
    "content": "Daylight Glare Probability (DGP) analysis is a two-step process. First, `rpict` is used to generate a high-quality 180° hemispherical fisheye HDR image (`-vth -vh 180 -vv 180`). Second, the `evalglare` program processes this image to calculate the DGP value. High-quality ambient parameters are essential for the `rpict` rendering. The view is defined in a separate .vf file.\n\nExample view file (`glare_view.vf`):\n`rvu -vth -vp 2.5 1.5 1.2 -vd 0 1 0 -vu 0 0 1 -vh 180 -vv 180`\n\nExample shell script (`run_dgp_analysis.sh`):\n```bash\n#!/bin/bash\n# --- Simulation Configuration ---\nPROJECT_NAME=\"office_test\"\nLATITUDE=34.05\nLONGITUDE=-118.24\nMERIDIAN=-120\nMONTH=6\nDAY=21\nTIME=14.5\n# Ambient Parameters (High Quality is ESSENTIAL)\nAB=6\nAD=2048\nAS=1024\nAR=512\nAA=0.15\n\n# --- File & Directory Setup ---\nGEOM_DIR=\"../01_geometry\"\nMAT_DIR=\"../02_materials\"\nSKY_DIR=\"../04_skies\"\nOCT_DIR=\"../06_octrees\"\nVIEW_DIR=\"../03_views\"\nRESULTS_DIR=\"../08_results\"\nIMG_DIR=\"../09_images/hdr\"\nmkdir -p $SKY_DIR $OCT_DIR $RESULTS_DIR $IMG_DIR\n\n# 1. Generate Sky\nSKY_FILE=\"${SKY_DIR}/${PROJECT_NAME}_${MONTH}_${DAY}_${TIME}.rad\"\ngensky $MONTH $DAY $TIME -a $LATITUDE -o $LONGITUDE -m $MERIDIAN > $SKY_FILE\n\n# 2. Create Octree\nOCTREE_FILE=\"${OCT_DIR}/${PROJECT_NAME}.oct\"\noconv ${MAT_DIR}/*.mat ${GEOM_DIR}/*.rad ${SKY_FILE} > $OCTREE_FILE\n\n# 3. Render Fisheye Image\nVIEW_FILE=\"${VIEW_DIR}/glare_view.vf\"\nHDR_IMAGE=\"${IMG_DIR}/${PROJECT_NAME}_glare.hdr\"\nrpict -vf $VIEW_FILE -x 1500 -y 1500 \\\n      -ab $AB -ad $AD -as $AS -ar $AR -aa $AA \\\n      $OCTREE_FILE > $HDR_IMAGE\n\n# 4. Run evalglare\nGLARE_RESULTS=\"${RESULTS_DIR}/${PROJECT_NAME}_dgp.txt\"\nGLARE_CHECK_IMG=\"${IMG_DIR}/${PROJECT_NAME}_glare_check.hdr\"\nevalglare -d -c $GLARE_CHECK_IMG $HDR_IMAGE > $GLARE_RESULTS\n\necho \"Glare analysis complete. Results in ${GLARE_RESULTS}\"\n```"
  },
  {
    "topic": "Post-Processing Annual Metrics with Python",
    "content": "After running an annual simulation (e.g., with the Three-Phase Method), the raw .ill file contains 8760 illuminance values for every point. This data can be processed into meaningful metrics like sDA, UDI, and ASE using a Python script with the numpy and pandas libraries.\n\nExample script (`post_process_annual.py`):\n```python\nimport numpy as np\nimport pandas as pd\nimport argparse\nimport os\n\ndef calculate_metrics(illuminance_file: str, output_dir: str, num_points: int):\n    try:\n        data = np.fromfile(illuminance_file, dtype=np.float32)\n        annual_illuminance = data.reshape(8760, num_points)\n    except Exception as e:\n        print(f\"Error reading file: {e}\")\n        return\n\n    # Occupancy: Weekdays, 8 AM to 6 PM (17:00)\n    time_index = pd.to_datetime(pd.date_range(start='2023-01-01', periods=8760, freq='h'))\n    occupied_mask = (time_index.hour >= 8) & (time_index.hour <= 17) & (time_index.dayofweek < 5)\n    occupied_illuminance = annual_illuminance[occupied_mask, :]\n\n    # sDA (300 lux, 50% of hours)\n    sDA_points = np.sum(occupied_illuminance >= 300, axis=0) / occupied_illuminance.shape[0]\n    sDA = np.sum(sDA_points >= 0.5) / num_points * 100\n\n    # ASE (1000 lux, 250 hours) - requires 5-Phase method for accuracy\n    ASE_points = np.sum(occupied_illuminance >= 1000, axis=0)\n    ASE = np.sum(ASE_points >= 250) / num_points * 100\n\n    # UDI\n    udi_f = np.mean(occupied_illuminance < 100, axis=0) * 100\n    udi_s = np.mean((occupied_illuminance >= 100) & (occupied_illuminance < 500), axis=0) * 100\n    udi_a = np.mean((occupied_illuminance >= 500) & (occupied_illuminance < 2000), axis=0) * 100\n    udi_e = np.mean(occupied_illuminance >= 2000, axis=0) * 100\n\n    # Save results\n    summary = {'sDA_300_50%': [f\"{sDA:.2f}%\"], 'ASE_1000_250h': [f\"{ASE:.2f}%\"]}\n    summary_df = pd.DataFrame(summary)\n    summary_path = os.path.join(output_dir, \"annual_metrics_summary.csv\")\n    summary_df.to_csv(summary_path, index=False)\n    print(f\"Summary results saved to {summary_path}\")\n\nif __name__ == \"__main__\":\n    parser = argparse.ArgumentParser()\n    parser.add_argument(\"illuminance_file\", type=str)\n    parser.add_argument(\"--points\", type=int, required=True)\n    parser.add_argument(\"--outdir\", type=str, default=\"../08_results\")\n    args = parser.parse_args()\n    calculate_metrics(args.illuminance_file, args.outdir, args.points)\n```"
  },
  {
    "topic": "Troubleshooting Common Simulation Issues",
    "content": "Common simulation problems and their solutions:\n- **Light leaks at corners:** Caused by coincident surfaces. Ensure geometry is well-constructed with no gaps.\n- **Large, splotchy, or blotchy patches:** The `-ad` (Ambient Divisions) parameter is too low. Solution: Double the value of `-ad` and re-render. Do not try to fix this by lowering `-aa`.\n- **Smooth shadows with blocky boundaries:** The `-aa` (Ambient Accuracy) is too high or `-ar` (Ambient Resolution) is too low, causing poor interpolation. Solution: Decrease `-aa` and/or increase `-ar`.\n- **Scene appears too dark far from windows:** Insufficient light propagation. The `-ab` value is too low, or the `-lw` (limit weight) value is too high. Solution: Increase `-ab` to 5 or higher and decrease `-lw` to 1e-5 or lower.\n- **Incorrect DGP results:** Could be multiple causes: 1) Input image was not a 180° fisheye view. 2) Rendering quality was too low, giving inaccurate background luminance. 3) Wrong threshold method in `evalglare`. Solution: Verify `rpict` command used `-vth -vh 180 -vv 180`, re-render with High-Fidelity settings, and use the `-t` option in `evalglare`."
  },
  {
    "topic": "Radiance Program: dctimestep",
    "content": "`dctimestep` computes annual simulation results by multiplying pre-calculated matrices. It typically takes a View matrix, a Transmission matrix (BSDF), a Daylight matrix, and a Sky matrix as input. Key options:\n- `-n nsteps`: Specifies the number of time steps (e.g., 8760 for an annual simulation).\n- `-o ospec`: Specifies an output file or a pattern for multiple output files (e.g., for generating an image per time step)."
  },
  {
    "topic": "Radiance Program: epw2wea",
    "content": "`epw2wea` is a utility that transforms an EnergyPlus weather data file (.epw) into the DAYSIM weather file format (.wea). This converted format is then suitable for use with the `gendaymtx` program to create annual sky matrices."
  },
  {
    "topic": "Radiance Program: evalglare",
    "content": "`evalglare` evaluates glare sources within a 180-degree fisheye HDR image to calculate metrics like Daylight Glare Probability (DGP). Key options:\n- `-d`: Produces detailed output, listing properties of each detected glare source.\n- `-c fname`: Creates a 'check file,' which is a copy of the input image with detected glare sources highlighted in color for verification.\n- `-t xpos ypos angle`: Defines a task area on the image. This is the recommended method for determining the glare source threshold, which is based on the average luminance within this task area."
  },
  {
    "topic": "Radiance Program: genBSDF",
    "content": "`genBSDF` computes a bidirectional scattering distribution function (BSDF) from a Radiance scene description of a fenestration system. The output is an XML file conforming to the LBNL Window 6 standard. Key options:\n- `-c Nsamp`: Specifies the number of samples per incident direction (default 2000).\n- `-n Nproc`: Specifies the number of simultaneous processes to run.\n- `-t4 Nlog2`: Computes a non-uniform BSDF represented as a rank 4 tensor tree, suitable for high-accuracy direct sun calculations in the 5-Phase Method."
  },
  {
    "topic": "Radiance Program: gendaymtx",
    "content": "`gendaymtx` generates an annual Perez sky matrix (.smx) from a weather file (.wea). The output matrix contains luminance values for each sky patch for every hour of the year. Key options:\n- `-m N`: Increases sky resolution using Reinhart subdivision (e.g., `-m 1` for 146 patches, `-m 4` for 2306 patches).\n- `-d`: Produces a sun-only matrix with no sky contributions.\n- `-s`: Excludes the direct solar component.\n- `-5`: A special option used in the 5-Phase Method to generate a high-resolution direct sun matrix."
  },
  {
    "topic": "Radiance Program: gensky",
    "content": "`gensky` generates a Radiance scene description for the CIE standard sky distribution for a specific month, day, and time. Key options:\n- `-c`: Generates a cloudy (overcast) sky.\n- `+s`: Generates a sunny sky with the sun.\n- `-s`: Generates a sunny sky without the sun.\n- `-a lat -o lon -m mer`: Specifies site latitude, longitude, and standard meridian for accurate sun position.\n- `-B irrad`: Sets the zenith brightness based on a specified horizontal diffuse irradiance (in W/m²). Used in Daylight Factor workflows."
  },
  {
    "topic": "Radiance Program: pcomb",
    "content": "`pcomb` is used to combine Radiance pictures of equal size. It can perform linear combinations or more complex pixel-by-pixel operations defined by an expression. It is used in the image-based 5-Phase Method to combine the results from the different calculation phases using an expression like `-e 'ro=ri(1)-ri(2)+ri(3);...'`."
  },
  {
    "topic": "Radiance Program: rcontrib",
    "content": "`rcontrib` is a core program used to compute contribution coefficients, forming the basis of matrix-based methods. It traces rays from sensors and bins the results based on which source modifier (e.g., a sky patch) the ray terminates on. Key options:\n- `-I+`: Specifies that irradiance contributions should be calculated.\n- `-f file.cal`: A function file that defines how to map ray directions to bin numbers.\n- `-b var -bn N`: Specifies the bin variable and the total number of bins.\n- `-m modifier`: The base name of the modifier for which to calculate coefficients."
  },
  {

    "topic": "Radiance Program: rfluxmtx",
    "content": "`rfluxmtx` is a utility that acts as a wrapper for `rcontrib` to simplify the process of creating flux transfer matrices, such as the View (V) and Daylight (D) matrices in the Three-Phase Method. It samples rays uniformly over a sender surface and records their arrival at receiver surfaces."
  },
  {
    "topic": "Radiance Program: rmtxop",
    "content": "`rmtxop` performs matrix operations on files. It is used in annual simulation workflows to convert the RGB irradiance output from `dctimestep` into a single lux value. It can also be used to add and subtract matrices, which is essential for assembling the final result in the 5-Phase Method."
  },
  {
    "topic": "Radiance Program: vwrays",
    "content": "`vwrays` computes the ray origin and direction for each pixel of a specified view. Its output is typically piped directly into another program like `rtrace` or `rcontrib`. It is a key component in generating image-based View Matrices for the Three-Phase Method, where it generates the initial rays for a camera view that are then traced back to the window surface by `rcontrib`."
  },
  {
    "topic": "Core Parameter Deep Dive: -ab (Ambient Bounces)",
    "content": "The `-ab` parameter specifies the maximum number of diffuse inter-reflections a ray will undergo. It controls the 'depth' of the simulation. A value of `-ab 0` disables the indirect calculation entirely, useful for isolating direct solar contribution or for very fast previews. For most analyses, a value between 3 and 5 is a good balance of accuracy and speed. Higher values (6-7) are necessary for complex geometries like deep rooms or spaces with light shelves, where light must follow a tortuous path. A high `-ab` value is ineffective unless the ray weight limit (`-lw`) is set to a very small value (e.g., 1e-6) and the reflection limit (`-lr`) is also increased, otherwise rays will terminate prematurely."
  },
  {
    "topic": "Core Parameter Deep Dive: -ad (Ambient Divisions)",
    "content": "The `-ad` parameter sets the number of sample rays sent to probe the hemisphere for indirect illuminance and is the primary control for resolving detail in the first-bounce indirect lighting. An insufficient `-ad` value is the most common cause of 'splotchy' or 'blotchy' artifacts, which are a clear sign of undersampling the hemispherical environment. The scale of these splotches is much larger than a single pixel, indicating a fundamental issue with the ambient calculation. The first and most effective step in troubleshooting these artifacts is to increase the `-ad` value, often by doubling it."
  },
  {
    "topic": "Core Parameter Deep Dive: -as (Ambient Super-samples)",
    "content": "The `-as` parameter defines the number of additional samples used to refine the initial ambient divisions in areas where high variance is detected. It is a secondary, more targeted refinement. If the initial `-ad` samples show high variation (e.g., one hits a dark wall, the next a bright window), Radiance sends out `-as` extra samples to get a more accurate average]. After setting a reasonable base value for `-ad`, increasing `-as` can efficiently clean up remaining noise without the high cost of universally increasing `-ad`. A good starting point is to set `-as` to half the value of `-ad`."
  },
  {
    "topic": "Core Parameter Deep Dive: -aa (Ambient Accuracy)",
    "content": "The `-aa` parameter controls the allowable error for the interpolation performed by the irradiance cache. It specifically manages *interpolation* error, not sampling error. Attempting to fix blotchy artifacts (an `-ad` problem) by lowering `-aa` is incorrect and will drastically increase computation time. The correct use for `-aa` is to resolve artifacts that appear as smooth but incorrect gradients or light 'bleeding' around corners. A special value of `-aa 0` disables interpolation entirely, which is computationally prohibitive and reserved for generating reference results."
  },
  {

    "topic": "Core Parameter Deep Dive: -dj (Direct Jittering)",
    "content": "The `-dj` parameter introduces a random element to shadow rays for area light sources. A value of 0 produces sharp, unrealistic hard-edged shadows. A positive value (e.g., `-dj 0.7`) distributes shadow rays across the source, correctly simulating soft-edged shadows (penumbras). For direct sun analysis with `rcontrib`, it is often better to use `-dj 0` to ensure the ray is always sent to the center of the solar disc for maximum consistency."
  },
  {
    "topic": "rpict View Types (-vt)",
    "content": "Radiance supports several camera projection models using the `-vt` option:\n- **v (Perspective):** Standard rectilinear projection for realistic architectural visualization. \n- **l (Parallel):** Orthographic projection with no perspective, used for elevations, plans, and axonometric views. \n- **c (Cylindrical Panorama):** Creates 360° panoramic images. \n- **h (Hemispherical Fisheye):** Equidistant projection of a 180° hemisphere. Required for `evalglare` analysis. \n- **a (Angular Fisheye):** Distance from center is proportional to view angle. Also suitable for glare analysis. \n- **s (Planisphere):** Stereographic projection that preserves angles, used for sun-path diagrams."
  },
  {
    "topic": "Daylight Factor (DF) Workflow Steps",
    "content": "The Daylight Factor (DF) workflow calculates interior illuminance under a standard CIE Overcast Sky and normalizes the results. The steps are:\n1. **Create the Sky:** Use `gensky` with the `-c` flag for an overcast sky and the `-B` flag to set a reference horizontal irradiance. To get 10,000 lux, the command is `!gensky -c -B 55.866 > sky.rad` (since 10000 lux / 179 lm/W ≈ 55.866 W/m²). \n2. **Create Octree:** Combine the sky, geometry, and materials with `oconv`. \n3. **Calculate Interior Illuminance:** Use the standard `rtrace` workflow with the generated octree and a points file. A minimum of `-ab 3` is recommended for overcast conditions. \n4. **Calculate DF:** Use `rcalc` to process the raw irradiance. The expression converts the result to illuminance, divides by the 10,000 lux reference, and multiplies by 100 to get a percentage. \nExample rcalc command: `cat interior_irradiance.dat | rcalc -e '$1=100 * (179*($1*0.265+$2*0.670+$3*0.065)) / 10000' > results_df.txt`"
  },
  {
    "topic": "Three-Phase Method (3PM) Matrix Definitions",
    "content": "The Three-Phase Method (3PM) decouples the annual simulation light path into four distinct matrices, allowing for modular and rapid re-calculation. The governing equation is `I = V * T * D * S`. The matrices are:\n- **S (Sky Matrix):** A matrix of sky patch luminances for every time step in a year, generated from a climate file using `gendaymtx`. \n- **D (Daylight Matrix):** Describes light transport from the sky patches to the exterior surface of the fenestration. Calculated with `rcontrib`. \n- **T (Transmission Matrix):** Describes the optical behavior of the fenestration system itself. This is a Bidirectional Scattering Distribution Function (BSDF), typically an XML file generated by `genBSDF` or LBNL WINDOW. \n- **V (View Matrix):** Describes light transport from the interior surface of the fenestration to the final sensor points. Calculated with `rcontrib`."
  },
  {
    "topic": "Five-Phase Method (5PM) Correction Logic",
    "content": "The Five-Phase Method (5PM) refines the 3PM by performing a high-accuracy calculation for the direct sun component and using it to correct the base resultThis is critical for calculating Annual Sunlight Exposure (ASE) or analyzing light-redirecting systemsThe logic is to calculate three separate illuminance time-series and combine them.\nThe final equation is:\n`I_5PM = I_3PM_total - I_3PM_direct + I_5PM_direct`\nWhere:\n- `I_3PM_total` is the result from a standard 3-Phase simulation. \n- `I_3PM_direct` is the inaccurate direct-sun-only portion calculated using the 3PM. \n- `I_5PM_direct` is the new, high-fidelity direct-sun-only portion calculated with a more accurate method."
  },
  {
    "topic": "Five-Phase Method: Advanced Matrices (Vd, Dd, Cds)",
    "content": "The 5-Phase method introduces new matrices to isolate and accurately calculate the direct sun component:\n- **Vd and Dd (Direct-only View and Daylight Matrices):** These are generated using `rcontrib` with `-ab 0` (or `-ab 1`) and a special 'black' octree where all non-source surfaces are perfect absorbers. This ensures only the direct, un-reflected light paths are calculated for the subtraction step. \n- **Cds (Direct Sun Coefficient Matrix):** This is a new high-fidelity matrix that directly relates the sun's position to the interior sensors, bypassing the coarse sky patch discretization of the 3PM. It is calculated using `rcontrib` with an octree that contains many explicit sun sources (`suns.rad`) and a high-resolution tensor tree BSDF for the window. "
  },
  {
    "topic": "Radiance Program: rtrace (Detailed Options)",
    "content": "`rtrace` traces rays from standard input through a scene octree. Its behavior is controlled by numerous options, many of which are shared with `rpict`. Key options unique to or commonly used with `rtrace` include:\n- **-I (Uppercase i):** A boolean switch to compute irradiance instead of radiance, interpreting input as a measurement point and surface normal. This is essential for grid-based illuminance analysis. \n- **-h:** A switch to suppress the information header in the output file. \n- **-w:** A switch to suppress non-fatal warning messages. \n- **-ospec:** Produces output fields according to a specification string, allowing you to trace a ray's path and properties (e.g., `-ot` to trace, `-op` for intersection point, `-on` for normal). \n- **-n nproc:** Executes in parallel on `nproc` local processes to speed up calculation. \n- **-x res, -y res:** Sets the x and y resolution, which helps structure the output and is useful when creating image files from `rtrace` data. "
  },
  {
    "topic": "Radiance Program: rpict (Detailed Options)",
    "content": "`rpict` generates a 2D image from a scene octree. In addition to ambient parameters, its output is primarily controlled by view parameters:\n- **-vt[v|l|c|h|a|s]:** Sets the view type (e.g., `v` for perspective, `h` for hemispherical fisheye).\n- **-vp x y z:** Sets the View Point (camera location).\n- **-vd xd yd zd:** Sets the View Direction vector.\n- **-vu xu yu zu:** Sets the View Up vector, defining vertical orientation.\n- **-vh val / -vv val:** Sets the horizontal/vertical field of view in degrees (or width/height for parallel views).\n- **-x res / -y res:** Sets the horizontal/vertical resolution in pixels.\n- **-i:** A boolean switch to compute irradiance for each pixel instead of radiance."
  },
  {
    "topic": "Full 3-Phase Method Matrix Generation Script",
    "content": "This script generates the Daylight and View matrices, which is the most computationally intensive step of the 3-Phase Method and only needs to be run once for a given building geometry. High-quality ambient parameters are essential as they affect all subsequent results. \n\n**Filename:** `run_3ph_matrix_generation.sh` \n**Location:** `07_scripts/` \n```bash\n#!/bin/bash\n# --- Configuration ---\nPROJECT_NAME=\"office_3ph\"\n# Use high-quality parameters for matrix generation.\nAB=7\nAD=4096\nAS=2048\nAR=1024\nAA=0.1\n\n# --- File & Directory Setup ---\nGEOM_DIR=\"../01_geometry\"\nMAT_DIR=\"../02_materials\"\nOCT_DIR=\"../06_octrees\"\nRESULTS_DIR=\"../08_results\"\nmkdir -p $OCT_DIR $RESULTS_DIR\n\n# 1. Create Exterior Octree (for Daylight Matrix)\n# Contains only exterior geometry and windows with a placeholder material.\necho \"1. Creating EXTERIOR octree...\"\nEXT_OCTREE=\"${OCT_DIR}/${PROJECT_NAME}_exterior.oct\"\noconv -f ${MAT_DIR}/exterior_materials.mat ${GEOM_DIR}/exterior_geometry.rad > $EXT_OCTREE\n\n# 2. Generate Daylight Matrix (Sky -> Window Exterior)\necho \"2. Generating Daylight Matrix...\"\nDAYLIGHT_MTX=\"${RESULTS_DIR}/daylight.mtx\"\n# rcontrib calculates contribution from sky modifiers, binned into 145 Reinhart patches.\nrcontrib -I+ -w -ab $AB -ad $AD -as $AS -ar $AR -aa $AA \\\n         -f reinhart.cal -b tbin -bn 145 -m sky_glow \\\n         -c 10000 \\\n         $EXT_OCTREE < <(oconv -f -i $EXT_OCTREE ${GEOM_DIR}/windows.rad | xform -m window_surface) > $DAYLIGHT_MTX\nif [ $? -ne 0 ]; then echo \"Error generating Daylight Matrix. Exiting.\"; exit 1; fi\n\n# 3. Create Interior Octree (for View Matrix)\n# Contains only interior geometry. The window is the sole light source.\necho \"3. Creating INTERIOR octree...\"\nINT_OCTREE=\"${OCT_DIR}/${PROJECT_NAME}_interior.oct\"\noconv -f ${MAT_DIR}/interior_materials.mat ${GEOM_DIR}/interior_geometry.rad > $INT_OCTREE\n\n# 4. Generate View Matrix (Window Interior -> Sensors)\necho \"4. Generating View Matrix...\"\nVIEW_MTX=\"${RESULTS_DIR}/view.mtx\"\nPOINTS_FILE=\"${RESULTS_DIR}/grid.pts\" # Assumes this exists\n# Trace from sensor points back to the window, binning results by the Klems basis.\nrcontrib -I+ -w -ab $AB -ad $AD -as $AS -ar $AR -aa $AA \\\n         -f klems_int.cal -b kbin -bn 145 -m window_material \\\n         $INT_OCTREE < $POINTS_FILE > $VIEW_MTX\nif [ $? -ne 0 ]; then echo \"Error generating View Matrix. Exiting.\"; exit 1; fi\n\necho \"---\"\necho \"Matrix generation complete.\"\necho \"Daylight Matrix: ${DAYLIGHT_MTX}\"\necho \"View Matrix: ${VIEW_MTX}\"\necho \"---\"\n```"
  },
  {
    "topic": "Full 3-Phase Method Annual Calculation Script",
    "content": "This script performs the final, rapid calculation for a 3-Phase Method annual simulation. It takes the pre-calculated matrices, a weather file, and a window BSDF file to generate a year's worth of illuminance data. The key advantage is that you can test different window systems by simply swapping the BSDF file and re-running this fast script. \n\n**Filename:** `run_3ph_annual.sh` \n**Location:** `07_scripts/` \n```bash\n#!/bin/bash\n# --- Configuration ---\nPROJECT_NAME=\"office_3ph\"\n# Provide a path to an EnergyPlus Weather (EPW) file.\nWEATHER_FILE=\"/path/to/your/USA_CA_Los-Angeles.Intl.AP.722950_TMY3.epw\"\n\n# --- File & Directory Setup ---\nBSDF_DIR=\"../05_bsdf\"\nRESULTS_DIR=\"../08_results\"\n\n# 1. Generate Sky Matrix from Weather File\necho \"1. Generating sky matrix from EPW file...\"\nSKY_MTX=\"${RESULTS_DIR}/sky.smx\"\n# epw2wea converts EPW to WEA format, then gendaymtx creates the annual sky matrix.\nepw2wea $WEATHER_FILE | gendaymtx -m 1 > $SKY_MTX\nif [ $? -ne 0 ]; then echo \"Error generating Sky Matrix. Exiting.\"; exit 1; fi\n\n# 2. Run dctimestep to get annual results\necho \"2. Running dctimestep for annual simulation...\"\nDAYLIGHT_MTX=\"${RESULTS_DIR}/daylight.mtx\"\nVIEW_MTX=\"${RESULTS_DIR}/view.mtx\"\n# This is the modular part: swap this XML file to test a different window.\nBSDF_FILE=\"${BSDF_DIR}/clear_glass.xml\"\nANNUAL_RESULTS=\"${RESULTS_DIR}/${PROJECT_NAME}.ill\"\n\n# dctimestep performs the final matrix multiplication for all 8760 hours.\ndctimestep $VIEW_MTX $BSDF_FILE $DAYLIGHT_MTX $SKY_MTX > $ANNUAL_RESULTS\nif [ $? -ne 0 ]; then echo \"Error during dctimestep. Exiting.\"; exit 1; fi\n\necho \"---\"\necho \"Annual simulation complete.\"\necho \"Annual illuminance results saved to: ${ANNUAL_RESULTS}\"\necho \"You can now run the post-processing script on this file.\"\necho \"---\"\n```"
  },
  {
    "topic": "Detailed 5-Phase Method Workflow Commands",
    "content": "The 5-Phase Method provides high accuracy for direct sun by correcting a standard 3-Phase result. The core equation is `I_5ph = I_3ph - I_ds-3ph + I_ds-5ph`. This involves calculating three separate time-series of illuminance and combining them. \n\n**Part 1: Calculate Standard 3-Phase Term (`I_3ph`)**\n1.  **Generate V, D, S, and T matrices:** Follow the standard 3-Phase method. Use a Klems basis BSDF for the T matrix (e.g., `bsdf/fullwindow_klems.xml`). \n2.  **Run `dctimestep`:**\n    ```bash\n    dctimestep -n 8760 -if matrices/viewmatrix.vmx bsdf/fullwindow_klems.xml \\\n               matrices/daylightmatrix.dmx matrices/OakLand.smx | \\\n  rcollate -h -oc 1 > data/i_3ph.txt\n    ```\n    \n\n**Part 2: Calculate Inaccurate Direct 3-Phase Term (`I_ds-3ph`)**\n1.  [**Create 'black' octree:** Make all non-glazing surfaces non-reflective to isolate direct paths. \n    ```bash\n    xform -m black objects/testroom_Swall.rad objects/testroom.rad ... | \\\n      oconv materials/testroom.mat - ... > octs/model_allblack.oct\n    ```\n    \n2.  **Generate Direct View Matrix (`Vd`):** Use the black octree with `-ab 1`. \n    ```bash\n    rcontrib -I+ -ab 1 ... -m viewsurf octs/model_allblack.oct < data/photocells.pts > matrices/viewmatrix_direct.vmx\n    ```\n    \n3.  **Generate Direct Daylight Matrix (`Dd`):** Use the black octree with `-ab 0`. \n    ```bash\n    genklemsamp ... | rcontrib -c 1000 -ab 0 ... -m sky_glow octs/model_allblack.oct > matrices/daylightmatrix_direct.dmx\n    ```\n    \n4.  **Generate Direct Sun-Only Sky Matrix (`Sds`):** Use `gendaymtx` with the `-d` flag. \n    ```bash\n    gendaymtx -of -d skies/OakLand.wea > matrices/OakLand_direct.smx\n    ```\n    \n5.  **Run `dctimestep`:**\n    ```bash\n    dctimestep -n 8760 -if matrices/viewmatrix_direct.vmx bsdf/fullwindow_klems.xml \\\n               matrices/daylightmatrix_direct.dmx matrices/OakLand_direct.smx | \\\n               rcollate -h -oc 1 > data/i_ds3ph.txt\n    ```\n    \n\n**Part 3: Calculate Accurate Direct 5-Phase Term (`I_ds-5ph`)**\n1.  **Generate `suns.rad` file:** Create a scene file with many (e.g., 5185) sun sources. \n    ```bash\n    echo \"void light solar 0 0 3 1e6 1e6 1e6\" > skies/suns.rad\n    cnt 5185 | rcalc -e MF:6 -f reinsrc.cal -e Rbin=recno \\\n      -o 'solar source sun${Rbin} 0 0 4 ${Dx} ${Dy} ${Dz} 0.533' >> skies/suns.rad\n    ```\n    \n2.  **Generate Tensor Tree BSDF:** Create a high-resolution BSDF (e.g., `bsdf/fullwindow_t45.xml`) using `genBSDF`. \n3.  **Create suns octree:** Combine the black geometry, suns file, and the fenestration geometry using the high-resolution BSDF proxy. \n    ```bash\n    xform -m black ... | oconv materials/testroom.mat - ... objects/glazing_bsdf.rad skies/suns.rad > octs/model_suns.oct\n    ```\n    \n4.  **Generate Sun Coefficient Matrix (`Cds`):** Use `rcontrib` to relate sun positions to sensors via the high-res BSDF. \n    ```bash\n    rcontrib -I -ab 1 -ad 65536 -dc 1 -dt 0 -dj 0 ... -m solar \\\n             octs/model_suns.oct < data/photocells.pts > matrices/directsun.dsmx\n    ```\n    \n5. **Generate 5-Phase Sun Matrix (`Ssun`):** Use `gendaymtx` with the `-5` flag. \n    ```bash\n    gendaymtx -5 -d -m 6 -of skies/OakLand.wea > matrices/OakLand_direct_m6.smx\n    ```\n    \n6.  **Run `dctimestep`:**\n    ```bash\n    dctimestep -n 8760 -if matrices/directsun.dsmx matrices/OakLand_direct_m6.smx | \\\n               rcollate -h -oc 1 > data/i_ds5ph.txt\n    ```\n    \n\n**Part 4: Combine Final Results**\n1.  **Use `rlam` and `rcalc`:** Paste the three data files together and perform the final calculation, then convert to lux. \n    ```bash\n    rlam data/i_3ph.txt data/i_ds3ph.txt data/i_ds5ph.txt | \\\n      rcalc -e 'r=$1-$4+$7; g=$2-$5+$8; b=$3-$6+$9' \\\n            -e '$1=179*(.265*r+.670*g+.065*b)' | \\\n      rcollate -h -fa1 -ic 8760 -t > results/illum.txt\n    ```\n    "
  },
  {
    "topic": "Radiance Program Deep Dive: rcontrib",
    "content": "`rcontrib` is a core Radiance program that computes ray coefficients for objects identified by their modifiers. It is essential for matrix-based daylighting methods. \n\n**Key Functionality:**\n- Traces rays from an input source (e.g., sensor points) and tallies their contributions from specified light sources or sky patches (modifiers). \n- The output can be a contribution value (if `-V+` is used) or a coefficient that must be multiplied by the source's radiance (`-V-`, the default for daylight coefficients). \n\n**Important Settings:**\n- **`-n nprocs`**: Runs the calculation in parallel on `nprocs` processes to speed up computation. \n- **`-o ospec`**: Defines the output destination. Can be a file or a command pipe. `%s` is replaced by the modifier name and `%d` by the bin number. \n- **`-m mod`**: Specifies a modifier name (e.g., `sky_glow`) for which to compute contributions. Can be repeated. \n- **`-M file`**: Reads a list of modifier names from a file. \n- **`-b binv`**: Defines a 'bin number' expression, allowing for finer resolution, such as dividing a sky dome into patches. \n- **`-bn nbins`**: Specifies the total number of bins in advance, which is critical for correctly formatted output. \n- **`-f source`**: Reads definitions and expressions (e.g., for binning) from a source file, like `reinhart.cal` or `klems_int.cal`. \n- **`-c count`**: Accumulates and averages contributions over `count` input rays. A value of 0 produces a single record summing all input, useful for reverse sampling. \n- **`rtrace options`**: Accepts most standard `rtrace` options to control the quality of the ray-tracing (e.g., `-ab`, `-ad`, `-aa`, `-I+` for irradiance). "
  },
  {
    "topic": "Radiance Program Deep Dive: rmtxop",
    "content": "`rmtxop` loads and performs operations on matrix files. It is a critical utility for combining results in multi-phase simulations and for converting data formats. \n\n**Key Operations:**\n- **Concatenation (`.`):** Standard matrix multiplication. \n- **Addition (`+`):** Element-wise addition of two matrices. \n- **Element-wise Multiplication (`*`):** Multiplies corresponding elements of two matrices. \n- **Element-wise Division (`/`):** Divides elements of the first matrix by the second. \n\n**Important Settings:**\n- **`-v`**: Verbose mode, announces each operation. \n- **`-f[afdc]`**: Sets the output format: `a` for ASCII, `f` for float, `d` for double, `c` for RGBE color. \n- **`-t`**: Transposes the matrix, swapping rows and columns. Can be applied to inputs or the final result. \n- **`-s sf`**: Applies a scalar factor `sf` to the matrix elements. \n- **`-c c1 c2 ...`**: Transforms element values using coefficients. For example, `-c 47.4 119.9 11.6` converts a 3-component RGB irradiance matrix to a 1-component illuminance (lux) matrix. "
  },
  {
    "topic": "Five-Phase Method: Core Concept and Equation",
    "content": "The five-phase method extends the three-phase method to provide higher accuracy by treating the direct solar component more precisely, which is particularly important for spaces with complex fenestration systems (CFS). The core equation combines three calculated terms: a standard three-phase result, a subtraction of the inaccurate direct sun component from that result, and the addition of a new, highly accurate direct sun component. The equation is: I_5ph = I_3ph - I_ds-3ph + I_ds-5ph."
  },
  {
    "topic": "Five-Phase Method: Prerequisites",
    "content": "To perform a five-phase simulation, you need a working Radiance installation, a Radiance model of the space (geometry and materials), a photocell points file (.pts) for sensor locations, an EPW weather file for the location, and several supporting calculation files. These support files include `klems_int.cal` for Klems basis sampling, `reinhart.cal` for sky/sun discretization, and `reinsrc.cal` for generating sun sources."
  },
  {
    "topic": "Five-Phase Method Step 1: Model Adjustments and BSDF Generation",
    "content": "Before matrix calculations, the model must be prepared. This involves creating special Radiance surfaces for the simulation: `viewmtxsurf.rad` (a glow surface on the window's interior face), `daymtxsurf.rad` (a surface on the exterior face), and `glazing_bsdf.rad` (a proxy surface that will use the high-resolution BSDF). A 'black' plastic material must also be added to the main materials file for use in later steps. The method requires two BSDFs: a high-resolution tensor tree BSDF (e.g., for the accurate sun calculation) and a standard Klems basis BSDF (for the three-phase components). Both are generated using the `genBSDF` program."
  },
  {

    "topic": "Five-Phase Method Step 2: Calculating I_3ph (Standard Three-Phase)",
    "content": "This step calculates the standard three-phase daylight result. First, an octree (`model_3ph.oct`) is created containing the room geometry, context, and the special matrix surfaces. Then, the required matrices are generated: the View Matrix (V) with `rcontrib`, the Daylight Matrix (D) using `genklemsamp` piped to `rcontrib`, and the annual Sky Matrix (S) using `epw2wea` and `gendaymtx`. Finally, these matrices are combined with the Klems basis BSDF (T) using `dctimestep` to produce the annual illuminance result `i_3ph.txt`."
  },
  {
    "topic": "Five-Phase Method Step 3: Calculating I_ds-3ph (Isolating 3-Phase Direct Sun)",
    "content": "This step isolates the direct solar contribution as calculated by the standard three-phase method, which will be subtracted from the total. A special octree (`model_allblack.oct`) is created where all scene materials are turned to black to prevent inter-reflections. Using this black octree, a direct-only View Matrix (Vd) is calculated with `rcontrib -ab 1`, and a direct-only Daylight Matrix (Dd) is calculated with `rcontrib -ab 0`. A direct-sun-only Sky Matrix (Sds) is created with `gendaymtx -d`. These are combined with the Klems BSDF using `dctimestep` to produce `i_ds3ph.txt`."
  },
  {
    "topic": "Five-Phase Method Step 4: Calculating I_ds-5ph (Accurate Direct Sun)",
    "content": "This step calculates the direct solar contribution with high accuracy. A Radiance file with many sun sources (`suns.rad`) is generated. A new 'black' octree (`model_suns.oct`) is created that includes the suns file and the fenestration geometry using the high-resolution tensor tree BSDF. A Direct Sun Coefficient Matrix (Cds) is calculated with `rcontrib` using this octree, relating the sun sources to the sensors. A special 5-phase direct sun matrix (Ssun) is created using `gendaymtx -5`. These two matrices are combined using `dctimestep` to produce the accurate direct sun result `i_ds5ph.txt`."
  },
  {
    "topic": "Five-Phase Method Step 5: Combining Components for Final Result",
    "content": "The final five-phase illuminance result is assembled from the three intermediate files. The `rlam` command is used to paste the records from `i_3ph.txt`, `i_ds3ph.txt`, and `i_ds5ph.txt` side-by-side. This output is piped to `rcalc`, which performs the core calculation `(I_3ph - I_ds-3ph + I_ds-5ph)` for each RGB channel and then converts the final RGB value into a single photopic illuminance value (lux). A final `rcollate` command formats the data into a usable table, typically with hours as rows and sensors as columns."
  },
  {
    "topic": "Radiance Philosophy: Visualization vs. Simulation",
    "content": "Radiance is a lighting visualization and simulation tool, not just a photorealistic renderer. Its primary goal is to generate images where calculated light levels quantitatively match actual physical conditions, making it a research and engineering instrument for predicting visible radiation distribution with verifiable accuracy. The core unit is spectral radiance (W⋅sr−1⋅m−2), from which all other photometric metrics like illuminance (lux) can be derived. The validity of a simulation depends entirely on the accuracy of its inputs, following the principle of 'garbage in, garbage out'."
  },
  {
    "topic": "How Radiance Defines Light Sources",
    "content": "In Radiance, light is an attribute of a surface, not an independent entity. There are no disembodied 'point lights'. To create a light source, you must first define a geometric object (e.g., a polygon or sphere) and then assign it a material property that makes it self-luminous. The object itself becomes the light source."
  },
  {
    "topic": "Radiance Ray-Tracing Algorithm",
    "content": "Radiance uses a light-backwards ray-tracing algorithm. Instead of tracing rays forward from light sources, it traces rays backward from the viewpoint (a virtual camera or measurement point). These rays bounce off surfaces based on their defined properties. When a ray path terminates at a light-emitting surface, its radiance contribution is calculated and added to the total value for the initial pixel or point. This process simulates both direct and indirect (diffuse interreflection) illumination."
  },
  {
    "topic": "Radiance Scene File (.rad) Structure",
    "content": "A .rad file is a human-readable plain text file that describes a 3D environment, including geometry, materials, and light sources. It supports four basic statement types:\n- Comments: Lines beginning with '#' are ignored.\n- Primitives: Core definitions for surfaces (polygons, spheres) and modifiers (materials, textures).\n- Aliases: Associates a new name with a previously defined primitive.\n- External Commands: Lines beginning with '!' are executed by the system shell, allowing for procedural geometry, file inclusion, and complex scene construction."
  },
  {
    "topic": "Radiance Universal Primitive Syntax",
    "content": "Every primitive in Radiance (materials, surfaces, etc.) follows a universal syntax:\n\nmodifier type identifier\nN S1 S2... SN\nI I1 I2... II\nM R1 R2... RM\n\n- modifier: The name of a previously defined primitive (like a material) that modifies the current one. Use 'void' for base materials.\n- type: A keyword specifying the primitive type (e.g., polygon, plastic, light).\n- identifier: A unique, user-defined name for the new primitive.\n- Argument Blocks: The next three lines contain string (N), integer (I), and real/floating-point (M) arguments, each preceded by a count of the arguments on that line."
  },
  {
    "topic": "Two-Step Principle of Creating a Light Source",
    "content": "Adding an artificial light source in Radiance is a two-step procedure:\n1. Define a Light Material: Create a material primitive using a light-emitting type (e.g., 'light', 'spotlight'). This defines the light's color and intensity and gives it a unique name.\n2. Apply the Material to Geometry: Create a geometric primitive (e.g., a polygon or sphere) and use the name of the light material from Step 1 as its modifier. This transforms the geometric object into a luminaire."
  },
  {
    "topic": "Example: Creating a Spherical Light Source",
    "content": "This example shows the two-step process for creating a spherical light source:\n\n```\n# Step 1: Define the light-emitting material.\n# The modifier is \"void\", type is \"light\", identifier is \"bright\".\nvoid light bright\n0\n0\n3  100  100  100  # R G B (Radiance in W/sr/m^2)\n\n# Step 2: Define geometry and apply the material.\n# The modifier is \"bright\", the material defined above.\n# The type is \"sphere\", the identifier is \"fixture\".\nbright sphere fixture\n0\n0\n4  2  1  1.5  0.125 # x_cen y_cen z_cen radius\n```"
  },
  {
    "topic": "Native Light Source Primitive: light",
    "content": "The 'light' primitive is the most fundamental light-emitting material. It models a surface as a perfect, uniform, diffuse emitter (Lambertian distribution), radiating light equally in all directions. It is ideal for bare lamps or simple luminous panels.\n\nSyntax:\nvoid light light_identifier\n0\n0\n3  Red_emission  Green_emission  Blue_emission\n\nThe three real arguments define the spectral radiance in W⋅sr−1⋅m−2 for the R, G, and B channels, controlling both color and intensity."
  },
  {
    "topic": "Native Light Source Primitive: spotlight",
    "content": "The 'spotlight' primitive models luminaires with directed output, like downlights or track lights. It defines color, intensity, direction, and angular spread.\n\nSyntax:\nvoid spotlight spotlight_identifier\n0\n0\n7  Red Green Blue  cone_angle  dx dy dz\n\n- Red, Green, Blue: Radiance in W⋅sr−1⋅m−2.\n- cone_angle: Full angular width of the emission cone in degrees (0-360).\n- dx, dy, dz: A 3D vector defining the beam's orientation."
  },
  {
    "topic": "spotlight: Direction Vector and Focal Length",
    "content": "The direction vector (dx dy dz) in a 'spotlight' primitive serves a dual purpose. Its orientation aims the light, but its magnitude (length) defines an effective focal length, simulating how a real lens or reflector collimates light. This changes the light falloff from the standard 1/r² to something closer to 1/(r+e)², where 'e' is the vector's magnitude. To simply aim the spotlight without this focusing effect, you must use a normalized direction vector (a vector with a length of 1.0), such as (0 0 -1) to aim straight down."
  },
  {
    "topic": "Native Light Source Primitive: glow",
    "content": "The 'glow' primitive is for self-luminous surfaces where the contribution to scene illumination can be precisely controlled or eliminated, making it an essential optimization tool. It is ideal for sources that must be visible but have negligible photometric impact, like indicator LEDs or exit signs.\n\nSyntax:\nvoid glow glow_identifier\n0\n0\n4  Red Green Blue  max_radius"
  },
  {
    "topic": "glow: The max_radius Parameter",
    "content": "The 'max_radius' parameter in a 'glow' material controls its participation in the lighting calculation:\n- If max_radius > 0: The surface acts as a light source, but only for objects within this specified radius.\n- If max_radius = 0 (default): The surface is visible and contributes to indirect (ambient) calculations, but never casts direct shadows.\n- If max_radius < 0: The surface is purely cosmetic. It is visible but completely excluded from all lighting calculations (direct and indirect). This is the most efficient option for things like indicator lights."
  },
  {
    "topic": "Native Light Source Primitive: illum",
    "content": "The 'illum' primitive is for modeling secondary light sources, like luminaire diffusers or windows. Its key feature is that it acts as a light source for calculations but adopts the appearance of a different, specified material when viewed directly. This provides a computationally efficient way to model things like translucent diffusers without modeling the lamp inside.\n\nSyntax:\nalternate_material illum illum_identifier\n0\n0\n3  Red Green Blue"
  },
  {
    "topic": "illum: Modeling Luminaire Diffusers",
    "content": "The expert workflow for modeling a luminaire with a diffuser uses the 'illum' primitive. Instead of modeling the fixture box and internal lamp, you only model the visible diffuser polygon. The process is:\n1. Define a standard material (e.g., 'trans' or 'plastic') that describes the visual appearance of the diffuser.\n2. Define an 'illum' material. Use the name of the appearance material from step 1 as its modifier. Set the RGB values to the desired light output of the fixture.\n3. Apply this 'illum' material to the diffuser polygon. This is more efficient because for the rest of the scene, the diffuser itself is the light source, but when viewed by the camera, it appears as the correct translucent material."
  },
  {
    "topic": "Summary of Light-Emitting Material Primitives",
    "content": "- light: General purpose diffuse emitter (bare bulb, luminous panel). Provides uniform, Lambertian emission.\n- spotlight: Directional luminaires (downlight, projector). Emits light within a defined cone; direction vector magnitude acts as a focal length.\n- glow: Computationally inexpensive sources (LEDs, screens). Contribution to scene illumination is controlled by `max_radius`, allowing for purely cosmetic sources.\n- illum: Secondary sources with a custom appearance (luminaire diffuser, luminous ceiling). Acts as a light source for calculations but appears as a different `alternate_material` when viewed directly."
  },
  {
    "topic": "Incorporating Photometric Data with ies2rad",
    "content": "Professional lighting design uses photometric data from manufacturers, typically in IES LM-63 format (.ies files). Radiance uses the 'ies2rad' command-line utility to translate this data into a Radiance scene description. It generates a .rad file containing the luminaire geometry and an 'illum' material, and a .dat file containing the interpolated photometric data that the 'illum' material references."
  },
  {
    "topic": "Key ies2rad Command-Line Options",
    "content": "- -o outname: Sets the root name for the output files.\n- -d units: Defines output dimensions ('m' for meters, 'f' for feet, etc.). Default is meters.\n- -m factor: Multiplies output by a factor. Used for applying a Light Loss Factor (LLF).\n- -c r g b: Sets a custom color. Used with -t default.\n- -t lamp: Specifies a lamp type to look up in lamp.tab. Using '-t default' forces the use of the -c color.\n- -p prefdir: Places output files into a subdirectory."
  },
  {
    "topic": "Workflow: Using an IES File",
    "content": "1. Acquire an .ies file from a manufacturer.\n2. Execute ies2rad in the terminal: `ies2rad downlight.ies`. This creates `downlight.rad` and `downlight.dat`.\n3. Integrate into your master scene file using the `!xform` command to place and orient the luminaire. Example: `!xform -t 1.5 2.0 2.8 -rx -90 downlight.rad`. This modular approach allows for easy placement of multiple instances."
  },
  {
    "topic": "Photometric Data Best Practices: Units",
    "content": "A mismatch between the units specified in the ies2rad command (-d flag) and the units used to model the main scene is one of the most common and catastrophic sources of error. If a scene is modeled in feet, but ies2rad is run with its default meter output, all lighting levels will be incorrect. It is imperative to ensure consistency."
  },
  {
    "topic": "Photometric Data Best Practices: Color",
    "content": "IES files do not contain spectral color information. For color consistency, the most robust practice is to override ies2rad's color inference. By using the `-t default` option along with `-c 1 1 1`, you can specify a color-balanced white light. Color temperature and chromaticity can then be adjusted globally in post-processing with the `pfilt` utility."
  },
  {
    "topic": "Geometric Primitives for Light Sources",
    "content": "A light-emitting material can be applied as a modifier to any standard geometric primitive to create a light source of a specific shape:\n- polygon: For flat, polygonal sources like troffers or linear fixtures.\n- sphere: For omnidirectional sources like bare lamps.\n- cylinder: For modeling linear fluorescent or LED tubes.\n- ring: For modeling the circular aperture of a recessed downlight."
  },
  {
    "topic": "Geometric Transformations with xform",
    "content": "`xform` is Radiance's utility for geometric transformations. Key options include:\n- -t x y z: Translate (Move).\n- -rx degrees: Rotate around the X-axis.\n- -ry degrees: Rotate around the Y-axis.\n- -rz degrees: Rotate around the Z-axis.\n- -s factor: Uniformly scale the object."
  },
  {
    "topic": "xform: Order of Operations",
    "content": "The order of transformation operations in `xform` is critical and non-commutative; they are applied sequentially. A common source of errors is incorrect ordering. The general rule of thumb is to perform scaling and rotation operations first, while the object is at the origin, and then perform the final translation to place it in the scene. For example, `!xform -rx 45 -t 5 0 0 object.rad` (rotate then translate) produces a different result than `!xform -t 5 0 0 -rx 45 object.rad` (translate then rotate)."
  },
  {
    "topic": "Creating Arrays of Luminaires with xform",
    "content": "`xform` can create arrays of objects efficiently using the `-a` (array) and `-i` (iterate) options.\n- `-a N`: Creates N copies of the input object. It works with the transform that immediately follows it, applying the transform cumulatively to each copy (0 times for the first, 1 time for the second, etc.).\n- `-i N`: Repeats the following transformation N times. It is often used to apply a global transformation to an entire array."
  },
  {
    "topic": "Best Practices for Scene File Management",
    "content": "For complex projects, it is best practice to use a modular file organization rather than a single monolithic .rad file. A typical project might be structured with separate files for materials (materials.rad), light definitions (lights.rad), and geometry (room_geom.rad). These components are then assembled in a master scene file using `!xform` and other commands. This approach makes scenes easier to manage, debug, and reuse."
  },
  {
    "topic": "Compiling a Scene with oconv",
    "content": "`oconv` is the Radiance scene compiler. It reads the textual .rad descriptions and builds a single binary file with a .oct extension. This octree is a spatial data structure that organizes the scene's geometry to make the ray-tracing process computationally feasible. Without this compilation step, rendering would be impossibly slow."
  },
  {
    "topic": "oconv: The Importance of Input File Order",
    "content": "A frequent source of errors is providing input files to `oconv` in the wrong order. A fundamental rule of Radiance is that a modifier must be defined before it is referenced. This means a file containing material definitions (e.g., materials.rad) must always be listed on the command line *before* any file containing geometry that uses those materials (e.g., room_geom.rad).\n- Correct: `oconv materials.rad room_geom.rad > scene.oct`\n- Incorrect: `oconv room_geom.rad materials.rad > scene.oct` (will cause an 'undefined modifier' error)."
  },
  {
    "topic": "Rendering an Image with rpict",
    "content": "`rpict` is the primary batch-mode rendering engine in Radiance. It takes a compiled .oct file and a set of parameters defining the view and calculation quality, and produces a high-dynamic-range (HDR) image. Key view parameters include:\n- -vp x y z: View point (camera location).\n- -vd dx dy dz: View direction (where the camera is pointing).\n- -vu ux uy uz: View up vector (defines 'up').\n- -vh angle / -vv angle: Horizontal and vertical field of view in degrees."
  },
  {
    "topic": "Troubleshooting: Noise and Splotches",
    "content": "The most common artifact in Radiance renderings is noise or splotchy patterns in indirectly lit areas. This is a direct result of insufficient sampling in the ambient calculation. The engine has not sent out enough rays to get a stable average of the incoming light. The solution is to increase the quality of the ambient calculation by raising the values of `-ad` (ambient divisions) and `-as` (ambient super-samples), which provides more samples to smooth out the result at the cost of longer render times."
  },
  {
    "topic": "Troubleshooting: Caustics and Specular Noise ('Fireflies')",
    "content": "Standard backward ray-tracing is inefficient at resolving focused specular reflections, like caustics from sunlight through glass or off a curved metal surface. Trying to solve this with `rpict` alone is often futile and results in extreme noise or 'fireflies'. For these cases, Radiance provides advanced tools like `mkillum` (a pre-calculation step for complex sources) or a full photon mapping extension, which is often the only viable method for cleanly rendering such scenes."
  },
  {
    "topic": "Radiance Engine in Modern GUI Tools",
    "content": "Many modern tools like ClimateStudio, Ladybug/Honeybee, and OpenStudio use Radiance as their simulation engine. These applications act as sophisticated wrappers, automatically generating .rad files and executing command-line programs like `oconv` and `rpict` behind the scenes. An understanding of the underlying Radiance principles is invaluable for troubleshooting unexpected results or extending the capabilities of these GUI-based tools."
  },
  {
    "topic": "Interplay of Ambient Calculation Parameters",
    "content": "The quality of a Radiance rendering is governed by a complex, interconnected system of ambient parameters. Changing one in isolation can have unexpected consequences. A critical relationship exists between ambient accuracy (-aa) and ambient divisions (-ad); increasing -aa without also significantly increasing -ad can be ineffective because the accuracy parameter needs a sufficient number of initial samples to accurately estimate and reduce error. The limit weight (-lw) sets the minimum contribution a ray must have to be worth tracing, preventing time from being wasted on insignificant light paths. The optimal settings are highly dependent on the specific scene geometry, materials, and lighting conditions."
  },
  {
    "topic": "Photometric Data Best Practices (LLF and Color)",
    "content": "When using the `ies2rad` utility, several best practices are crucial for a physically valid simulation. The candela multiplier (`-m`) should be reserved for applying known, physically-justifiable scaling factors, most commonly a Light Loss Factor (LLF) to account for lamp depreciation and dirt accumulation (e.g., `-m 0.85`). It should not be used as an arbitrary 'fudge factor' to force a simulation to match a result, as this undermines the predictive power of the simulation. Since IES files do not contain spectral color information, the most robust practice for color consistency is to override `ies2rad`'s automatic color inference. Using the `-t default` option along with `-c 1 1 1` ensures all luminaires contribute a neutral white light, allowing color temperature to be adjusted with greater control in post-processing using the `pfilt` utility."
  },
  {
    "topic": "xform: Deconstructing a 2D Array Command",
    "content": "The `xform` utility can create complex arrays with a single command by chaining the `-a` (array) flag. For example, the command `xform -rz 90 -a 5 -t 2 0 0 -a 4 -t 0 1.5 0 light.rad` builds a 5x4 grid. The operations are sequential:\n1. `-rz 90`: An initial rotation is applied to the base `light.rad` object.\n2. `-a 5 -t 2 0 0`: This creates the first dimension of the array. It makes 5 copies of the rotated object, cumulatively translating each copy by (2 0 0), creating a row of 5 lights spaced 2 units apart in the X direction.\n3. `-a 4 -t 0 1.5 0`: This creates the second dimension. It takes the entire row of 5 lights and duplicates it 4 times, cumulatively translating each new row by (0 1.5 0) to form the final 5x4 grid."
  },
  {
    "topic": "Complete Command-Line Rendering Script",
    "content": "A complete end-to-end rendering workflow can be automated with a bash shell script. This template defines project variables, compiles the scene files into an octree using `oconv`, renders the image with `rpict` using a set of quality parameters, and displays the result.\n```bash\n#!/bin/bash\n# --- 1. Define Project Variables ---\nBASENAME=\"office_scene\"\nMATERIALS=\"materials.rad lights.rad\"\nGEOMETRY=\"room_geom.rad furniture.rad\"\nSCENE_FILES=\"$MATERIALS $GEOMETRY\"\nOCTREE_FILE=\"${BASENAME}.oct\"\nPICTURE_FILE=\"${BASENAME}.pic\"\nVIEW_FILE=\"view1.vf\"\n\n# --- 2. Create the Octree with oconv ---\necho \"Creating octree: $OCTREE_FILE...\"\noconv -f $SCENE_FILES > $OCTREE_FILE\nif [ $? -ne 0 ]; then\n    echo \"Error: oconv failed. Aborting.\"\n    exit 1\nfi\necho \"Octree created successfully.\"\n\n# --- 3. Render the Image with rpict ---\necho \"Rendering picture: $PICTURE_FILE...\"\nrpict -vf $VIEW_FILE \\\n      -ab 4 \\\n      -ad 1024 \\\n      -as 256 \\\n      -aa 0.15 \\\n      -lw 0.005 \\\n      $OCTREE_FILE > $PICTURE_FILE\nif [ $? -ne 0 ]; then\n    echo \"Error: rpict failed. Aborting.\"\n    exit 1\nfi\necho \"Rendering complete.\"\n\n# --- 4. View the Result ---\necho \"Displaying image...\"\nximage $PICTURE_FILE &\nexit 0\n```"
  },
  {
    "topic": "Advanced Source Sampling (mkillum and Photon Mapping)",
    "content": "Standard backward ray-tracing is inefficient for rendering lighting paths that involve focused specular reflections, which can result in extreme noise or 'fireflies'. For these difficult cases, Radiance provides advanced tools .\n- **mkillum**: This program performs a pre-calculation step by tracing rays forward from a difficult-to-sample surface (like a sunlit window) to determine its light distribution. It then replaces that complex source with a simpler, more efficient secondary `illum` source for the final rendering .\n- **Photon Mapping**: For the most challenging scenes with caustics, Radiance offers a photon mapping extension. This forward ray-tracing technique emits 'photons' from light sources, which are stored on the surfaces they strike. The final rendering uses this 'photon map' to accurately calculate illumination from these difficult light paths, and it is often the only viable method for such scenes."
  },
  {
    "topic": "Limitations of Tristimulus (RGB) Simulation for Non-Visual Effects",
    "content": "Standard physically-based lighting simulation tools like Radiance traditionally use a tristimulus (RGB) color space to prioritize visual accuracy and efficiency. This model collapses complex spectral power distributions (SPDs) into three values, discarding a significant amount of spectral information. While effective for visual rendering, this is insufficient for predicting the non-visual, biological effects of light. These effects are mediated by a separate pathway involving intrinsically photosensitive Retinal Ganglion Cells (ipRGCs) containing the photopigment melanopsin. The melanopic system has a peak sensitivity in the blue region of the spectrum (around 460–490 nm), which is fundamentally different from the photopic (daylight vision) system's peak sensitivity at approximately 555 nm (green-yellow). Furthermore, other non-visual pathways, such as the one mediated by neuropsin (sensitive to violet light near 380 nm), influence core body functions. Because these biological action spectra are distinct from the photopic curve, a tristimulus simulation or a simple photometric value like lux is an insufficient and often misleading predictor of light's non-visual impact, necessitating a simulation methodology with higher spectral resolution."
  },
  {
    "topic": "Spectral Analysis (9-Channel): N-Channel Methodology",
    "content": "The 9-channel spectral methodology is a technique to overcome the limitations of Radiance's 3-channel engine for spectral analysis. It works by partitioning the visible spectrum (typically 380 nm to 780 nm) into 'N' discrete wavelength bins. The Radiance simulation is then executed N/3 times. In each execution, Radiance's three color channels (R, G, B) are repurposed to represent three consecutive spectral bins. For example, in the first run, R, G, and B might represent bins 1, 2, and 3. In the second run, they would represent bins 4, 5, and 6, and so on. The final results from each run are then aggregated in a post-processing step to reconstruct a single N-channel spectral result. This methodology uses a 9-channel approach, requiring three distinct Radiance simulation runs. This 9-channel method is an optimized compromise between accuracy and computational cost, reducing the mean absolute percent error for predicting lighting metrics from ~19% (for 3-band RGB) to around 4% while remaining computationally feasible for architectural design workflows."
  },
  {
    "topic": "Spectral Analysis (9-Channel): Wavelength Bins",
    "content": "The precise definition of the wavelength intervals is the cornerstone of the 9-channel spectral methodology. All spectral data for materials and light sources must be processed according to these specific bins:\n- Channel 1: 380–424 nm\n- Channel 2: 425–454 nm\n- Channel 3: 455–479 nm\n- Channel 4: 480–504 nm\n- Channel 5: 505–529 nm\n- Channel 6: 530–559 nm\n- Channel 7: 560–599 nm\n- Channel 8: 600–644 nm\n- Channel 9: 645–780 nm"
  },
  {
    "topic": "Spectral Analysis (9-Channel): Pre-Processing Spectral Data",
    "content": "The core pre-processing task is to convert continuous spectral data (SPDs for light sources, SRDs/STDs for materials) into a single representative value for each of the nine channels. This is accomplished by calculating the arithmetic mean of all spectral data points that fall within the defined wavelength range for each bin. The formula for the binned value, V_n, for a given channel n is:\n\nV_n = (1/k) * Σ P(λ_i) for all i where λ_start,n ≤ λ_i ≤ λ_end,n\n\nwhere P(λ_i) is the spectral value at wavelength λ_i and k is the total number of data points within the bin. This calculation is performed for all nine channels, resulting in a nine-element vector (V1, V2, ..., V9) that represents the binned spectral properties."
  },
  {
    "topic": "Spectral Analysis (9-Channel): Formatting for Radiance",
    "content": "Once a nine-element vector of binned spectral values is calculated for a material, it must be structured into three separate Radiance material files (.rad), one for each of the three simulation runs. The binned values are assigned sequentially to the R, G, and B parameters of a Radiance material primitive. For a 'plastic' material with binned reflectance values V1 through V9, the files would be structured as:\n- materials_c1-3.rad: `void plastic material_name ... <V_1> <V_2> <V_3> ...`\n- materials_c4-6.rad: `void plastic material_name ... <V_4> <V_5> <V_6> ...`\n- materials_c7-9.rad: `void plastic material_name ... <V_7> <V_8> <V_9> ...`\nFor transparent materials like 'glass', it is critical to first convert the binned spectral transmittance (T_n) to spectral transmissivity (t_n) for each channel using the formula derived from Stokes' equations before populating the material definitions: \n\nt_n = (sqrt((1-R_n)^4 + 4*R_n^2*T_n^2) - (1-R_n)^2) / (2*R_n*T_n)"
  },
  {
    "topic": "Spectral Analysis (9-Channel): Two-Pass Method for Sky/Sun Generation",
    "content": "To create a spectrally accurate yet energetically consistent sky model, Ray Modeler uses a 'two-pass' method with the `gendaylit` program. The challenge is to replace the standard white sun/sky with spectrally-defined ones without corrupting the energy balance based on input DNI and DHI values.\n\nPass 1: Establish Baseline. `gendaylit` is run with the `-W <DNI> <DHI>` option. The baseline sun radiance values (R_rad, G_rad, B_rad) in W/sr/m² are parsed from the output 'sun' primitive.\n\nPass 2: Generate Spectral Sky. A scaling coefficient is calculated to match the brightness of the custom binned solar spectrum to the baseline sun. The final sky files are then generated by running `gendaylit` again, but this time its standard output is piped through a stream editor like `sed` to dynamically replace the default `void` modifiers with custom `colorfunc` modifiers that apply the scaled spectral sun colors and the unscaled spectral sky colors."
  },
  {
    "topic": "Spectral Analysis (9-Channel): Solar Scaling Coefficient Calculation",
    "content": "The solar scaling coefficient (C_scale) ensures the final spectral sun has the same perceived brightness as the physically correct baseline sun from `gendaylit`. The normalization is performed in the photometric domain (luminance) to derive a correction factor that is then applied back in the radiometric domain.\n1.  **Calculate Baseline Photopic Luminance (L_base):** Using the parsed radiance values (R_rad, G_rad, B_rad) from Pass 1 and standard Radiance weighting coefficients.\n    `L_base = 179 * (0.2651*R_rad + 0.670*G_rad + 0.065*B_rad)`\n2.  **Calculate Unscaled Spectral Photopic Luminance (L_spec,unscaled):** Using the nine binned solar SPD values (S1...S9) and the corresponding photopic weighting coefficients (P1...P9).\n    `L_spec,unscaled = 179 * Σ(S_n * P_n)`\n3.  **Calculate the Scaling Coefficient (C_scale):** The ratio of the two luminances.\n    `C_scale = L_base / L_spec,unscaled`\n4.  **Apply the Coefficient:** Each of the nine binned solar SPD values is multiplied by C_scale (`S_n,scaled = S_n * C_scale`) before being used in the Pass 2 sky generation."
  },
  {
    "topic": "Spectral Analysis (9-Channel): Scene Compilation and Octrees",
    "content": "For a 9-channel simulation, the scene must be compiled into three separate octrees, one for each set of spectral channels. For each run, the scene description files are assembled. For channels 1-3, this includes the spectral sky file (`sky_c1-3.rad`), the spectral material file (`materials_c1-3.rad`), and the common geometry file(s). The `oconv` command is used to compile these into a binary `.oct` file. Using the `-f` (frozen) option is strongly recommended. This option embeds the full content of all input files directly into the octree, creating a larger but fully self-contained and portable file that is robust against changes to the source `.rad` files. This process is repeated to create `scene_c1-3.oct`, `scene_c4-6.oct`, and `scene_c7-9.oct`."
  },
  {
    "topic": "Spectral Analysis (9-Channel): Daylight Coefficient (DC) Method",
    "content": "The Daylight Coefficient (DC) method is the fundamental technique that makes annual spectral analysis computationally feasible. Instead of running a full rendering for every hour (which would require 8760 hours * 3 runs = 26,280 rpict executions), the DC method pre-calculates the geometric light transport. The `rcontrib` program is used to calculate a Daylight Matrix, which describes the contribution of each sky patch to each sensor point. This computationally intensive ray-tracing is performed only three times in total—once for each of the three channel-set octrees. Key `rcontrib` options for this workflow include:\n- `-I+`: To compute irradiance (W/m²).\n- `-f reinhart.cal`: To use the Reinhart sky subdivision for accurately capturing the sun.\n- `-b rbin -bn Nrbins`: To assign contributions to the correct Reinhart sky patch bin.\n- `-m skyfunc -m solar`: To generate coefficients for both the diffuse sky and the direct sun. \nThe result is three DC matrices (`dc_matrix_c1-3.dat`, etc.) that represent the full 9-channel spectral response of the scene."
  },
  {
    "topic": "Spectral Analysis (9-Channel): Post-Processing and Metric Calculation",
    "content": "The final stage transforms the raw 9-channel simulation output into meaningful metrics. The data from the three separate simulation runs (e.g., three DC matrices) is aggregated into a single 9-channel dataset. Final metrics are then calculated via a weighted sum, mathematically equivalent to a dot product. The general formula is:\n\nMetric = C * Σ (E_n * W_n)\n\n- `E_n` is the calculated irradiance (W/m²) for channel n.\n- `W_n` is the pre-calculated, dimensionless weighting coefficient for channel n specific to the metric (e.g., photopic, melanopic).\n- `C` is a final conversion constant. For photopic illuminance (lux) and Melanopic EDI (lux), this constant is the standard luminous efficacy of 179 lm/W. \nIf images were generated instead of matrices, the Radiance command `pcomb` is used to combine the three 3-channel images into a single multi-channel data file for processing."
  },
  {
    "topic": "Spectral Analysis (9-Channel): Weighting Coefficients for Metrics",
    "content": "To calculate final metrics from the 9-channel spectral irradiance, the following weighting coefficients, derived by integrating standardized spectral sensitivity curves over each wavelength bin, are used in a weighted sum:\n- **Photopic Weights (V(λ)):** [0.0003, 0.0232, 0.1465, 0.3644, 0.7386, 0.9859, 0.8654, 0.3804, 0.0535]\n- **Melanopic Weights (S_mel(λ)):** [0.0335, 0.4021, 0.7932, 0.8876, 0.6548, 0.3923, 0.1256, 0.0177, 0.0010]\n- **Neuropic Weights (Neuropsin):** [0.7259, 0.2312, 0.0000, 0.0000, 0.0000, 0.0000, 0.0000, 0.0000, 0.0000]"
  },
  {
    "topic": "Spectral Analysis (9-Channel): Full 9-Channel Simulation Recipe",
    "content": "The document provides a self-contained recipe for implementing the 9-channel spectral simulation in Radiance. This recipe is a practical template that automates the entire point-in-time workflow for both image-based and grid-based analysis. It includes a master shell script (`run_spectral_simulation.sh`), placeholder input files for geometry (`geometry.rad`), spectrally binned materials (`materials_c*.rad`), spectral power distributions (`sun.spd`, `sky.spd`), sensor points (`sensor_points.txt`), a view file (`view.vf`), and function files for metric calculations (`*.cal`). To use it, all files are placed in a single directory, the script is made executable, and then it is run from the terminal."
  },
  {
    "topic": "Spectral Analysis (9-Channel): 9-Channel Master Script (`run_spectral_simulation.sh`)",
    "content": "This master shell script orchestrates the entire 9-channel workflow. It is structured into several automated stages:\n1.  **Configuration**: Defines user-modifiable parameters for location, time, irradiance (DNI/DHI), scene files, and Radiance quality settings.\n2.  **Pre-processing**: Reads and bins the `sun.spd` and `sky.spd` files into 9-channel values using `awk` to average the data within the specified wavelength ranges for each bin.\n3.  **Spectral Sky Generation**: Implements the two-pass method. Pass 1 runs `gendaylit` to get a baseline sun radiance. It then calculates the scaling coefficient `C_SCALE` by comparing the baseline photopic luminance to the unscaled spectral luminance. Pass 2 generates three final sky files by creating `colorfunc` modifiers with the scaled sun values and programmatically inserting them into a new `gendaylit` output using `sed`.\n4.  **Scene Compilation**: Creates three separate octrees (`scene_c1-3.oct`, etc.) by running `oconv` for each set of spectral channels, combining the appropriate sky, material, and geometry files.\n5.  **Simulation Execution**: For each of the three octrees, it runs both an image-based simulation using `rpict` and a grid-based simulation using `rtrace`.\n6.  **Post-Processing**: Uses `pcomb` to combine the three HDR image results into final photopic, melanopic, and neuropic luminance images by applying the weighting coefficients in an expression. It also uses `paste` and `rcalc` to combine the three grid-based results and calculate the final photopic, melanopic, and neuropic illuminance values."
  },
  {
    "topic": "Spectral Analysis (9-Channel): Example Geometry (`geometry.rad`)",
    "content": "The recipe includes a simple shoebox room model defined in `geometry.rad` with all units in meters. The geometry is constructed from several `polygon` primitives:\n- A floor from (0,0,0) to (10,6,0) using `wall_material`.\n- A ceiling at a height of 3 meters using `ceiling_material`.\n- Four walls (back, right, left, front) using `wall_material`.\n- The front wall is composed of four separate polygons to create an opening for a window.\n- A window made of a single polygon from (2,6,1) to (8,6,2) is defined using `glass_material`."
  },
  {
    "topic": "Spectral Analysis (9-Channel): Example 9-Channel Materials",
    "content": "The recipe provides three separate material files to define the spectral properties for each of the three simulation runs.\n- **`materials_c1-3.rad`**: Defines materials for the first three spectral bins (380-479 nm). It includes a `plastic` `wall_material` with RGB values of `0.55 0.52 0.48`, a `plastic` `ceiling_material` with RGB `0.82 0.81 0.80`, and a `glass` material with transmissivity `0.91 0.90 0.89`.\n- **`materials_c4-6.rad`**: Defines materials for the middle three spectral bins (480-559 nm). The `wall_material` is `0.50 0.51 0.53`, `ceiling_material` is `0.81 0.82 0.82`, and `glass` is `0.90 0.91 0.91`.\n- **`materials_c7-9.rad`**: Defines materials for the final three spectral bins (560-780 nm). The `wall_material` is `0.55 0.56 0.58`, `ceiling_material` is `0.83 0.83 0.84`, and `glass` is `0.90 0.89 0.88`."
  },
  {
    "topic": "Spectral Analysis (9-Channel): Example Input Files (SPD, Sensors, View)",
    "content": "The recipe includes several small text files that serve as inputs to the simulation script:\n- **`sun.spd` and `sky.spd`**: Simple two-column ASCII files representing the Spectral Power Distribution for the sun and sky, with wavelength in nm in the first column and a relative value in the second.\n- **`sensor_points.txt`**: Defines the locations and normal vectors for grid-based calculations. Each line has the format `x_pos y_pos z_pos x_dir y_dir z_dir`. The example provides three horizontal sensors at a height of 0.85m.\n- **`view.vf`**: Defines the camera parameters for `rpict` to render an HDR image. The example uses a perspective view (`-vtv`) with a 90-degree horizontal and vertical field of view (`-vh 90 -vv 90`)."
  },
  {
    "topic": "Spectral Analysis (3-Channel): Full 3-Channel Simulation Recipe",
    "content": "The document also provides a recipe for a simplified 3-channel spectral simulation. This approach is computationally faster as it requires only a single Radiance run. While it offers lower spectral resolution than the 9-channel method, it can still provide a significant improvement over standard non-spectral simulations. The structure is similar to the 9-channel recipe for easy comparison, including a master script (`run_3channel_simulation.sh`), geometry, a single material file (`materials_3ch.rad`), SPD files, and sensor/view files."
  },
  {
    "topic": "Spectral Analysis (3-Channel): 3-Channel Master Script (`run_3channel_simulation.sh`)",
    "content": "This script automates the 3-channel workflow, following a similar logic to the 9-channel version but simplified to a single pass.\n1.  **Pre-processing**: Bins the SPD data into just three channels based on standard Radiance RGB wavelength intervals: B (380-498 nm), G (498-586 nm), and R (586-780 nm).\n2. **Sky Generation**: Implements the same two-pass `gendaylit` method, but calculates the scaling coefficient using the standard Radiance photopic weights for the three binned values (`0.2651*R + 0.670*G + 0.065*B`). It generates only a single final spectral sky file.\n3.  **Compilation & Simulation**: Runs `oconv` once to create a single octree (`scene_3ch.oct`) and runs `rpict` and `rtrace` once.\n4.  **Post-Processing**: Uses `pcomb` and `rcalc` to calculate final metrics from the single 3-channel result file, applying pre-calculated 3-channel weighting coefficients for photopic, melanopic, and neuropic responses."
  },
    {
    "topic": "Recommended Project Directory Structure",
    "content": "A well-organized project directory is critical for managing complexity and ensuring repeatability in Radiance simulations. A recommended structure separates files by function into numbered folders, which mirrors the logical progression of the analysis workflow. This structure typically includes folders like `01_geometry/` for .rad files, `02_materials/` for material definitions, `06_octrees/` for compiled .oct files, `07_scripts/` for execution scripts, and `08_results/` for numerical output. Using relative paths within scripts (e.g., `../01_geometry/room.rad`) ensures that the entire project is portable and can be shared without breaking file links."
  },
  {
    "topic": "Core Ambient Calculation Parameters Explained",
    "content": "The accuracy of indirect illumination is governed by the irradiance cache, controlled by several key parameters. `-ab` (Ambient Bounces) sets the maximum number of diffuse inter-reflections, controlling the simulation's 'depth'. A value of 3-5 is standard. `-ad` (Ambient Divisions) sets the number of initial sample rays to calculate indirect light and is the primary control for fixing 'splotchy' artifacts. `-as` (Ambient Super-samples) adds more samples in areas of high variance to refine the `-ad` calculation. `-aa` (Ambient Accuracy) controls the allowable error for *interpolation* between cached values, and should not be used to fix sampling issues like splotches."
  },
  {
    "topic": "Core Direct Calculation Parameters Explained",
    "content": "The direct calculation handles light traveling from a source to a surface without bounces and is crucial for accurate shadows. `-dj` (Direct Jittering) introduces randomness to shadow rays from area sources to correctly simulate soft-edged shadows (penumbras)]. `-dt` (Direct Thresholding) is an optimization that halts shadow testing for sources with insignificant contribution. For high-accuracy simulations, especially with direct sun, it is standard to use `-dt 0` with `-dc 1` (Direct Certainty), which forces a full calculation for all light sources and disables statistical approximation."
  },
  {
    "topic": "Grid-Based Illuminance Workflow with rtrace",
    "content": "The fundamental method for quantitative daylighting analysis is to calculate illuminance (lux) on a grid of sensor points. The workflow involves creating a text file (.pts) where each line defines a sensor's location and orientation (X Y Z Vx Vy Vz). The `rtrace` program, using the `-I` switch, traces rays from these points to compute irradiance in W/m². This raw RGB output is then piped to the `rcalc` utility to be converted into a single photopic illuminance value in lux, using the standard luminous efficacy for daylight and CIE photopic weighting factors."
  },
  {
    "topic": "Daylight Glare Probability (DGP) Workflow",
    "content": "Calculating Daylight Glare Probability (DGP) is a two-stage process for assessing visual discomfort. First, `rpict` is used to render a high-fidelity 180° hemispherical fisheye HDR image, which is a mandatory input format (`-vth -vh 180 -vv 180`). High-quality ambient parameters are essential for this rendering, as an inaccurate background luminance will invalidate the result. Second, the `evalglare` program processes this HDR image to identify glare sources and compute the final DGP value. The resulting DGP value can be interpreted on a scale from imperceptible (< 0.35) to intolerable (>= 0.45)."
  },
  {
    "topic": "Daylight Factor (DF) Calculation Workflow",
    "content": "Daylight Factor (DF) is a classic metric expressing interior illuminance as a percentage of the available exterior illuminance under a standard CIE Overcast Sky. The Radiance workflow involves using the `gensky` program with the `-c` flag for an overcast sky and the `-B` flag to set a specific reference horizontal irradiance. To normalize to a 10,000 lux exterior reference, the irradiance is set to 55.866 W/m² (10000 lux / 179 lm/W). After calculating interior illuminance with `rtrace`, `rcalc` is used to divide the interior result by the reference value and multiply by 100 to get the final DF percentage."
  },
  {
    "topic": "Three-Phase Method (3PM) for Annual Simulation",
    "content": "The Three-Phase Method (3PM) is a modular approach for annual simulations that decouples the light path into distinct matrices: I = V * T * D * S. V is the View Matrix (window interior to sensor), T is the Transmission Matrix (a BSDF file for the window), D is the Daylight Matrix (sky to window exterior), and S is the Sky Matrix (climate data). Its greatest strength is flexibility; a designer can rapidly test different window systems by swapping the T matrix (BSDF file) and re-running a fast final matrix multiplication with `dctimestep`, without repeating the time-consuming generation of the V and D matrices."
  },
  {
    "topic": "Five-Phase Method (5PM) for High-Fidelity Sunlight",
    "content": "The Five-Phase Method (5PM) is the state-of-the-art technique for annual simulations where direct sunlight is critical, such as for calculating Annual Sunlight Exposure (ASE). It corrects the 3PM's tendency to 'smear' the sun's contribution across a large sky patch. The methodology is a corrective process defined by the equation: I_5PM = I_3PM_total - I_3PM_direct + I_5PM_direct. It works by subtracting the inaccurate direct-sun portion calculated via the 3PM and adding back a new, high-fidelity direct-sun portion calculated with a more accurate, high-resolution method."
  },
  {
    "topic": "Troubleshooting: Splotchy or Blotchy Renderings",
    "content": "The most common visual artifact in Radiance renderings is large, splotchy, or blotchy patches in areas of indirect light. This is a clear sign of undersampling the hemispherical environment during the ambient calculation. The cause is an insufficient value for the `-ad` (Ambient Divisions) parameter. The first and most effective solution is to increase the value of `-ad`, often by doubling it, and re-rendering the scene. It is a common mistake to try and fix this issue by lowering `-aa` (Ambient Accuracy), but this is incorrect as `-aa` only controls interpolation error, not sampling error, and will lead to drastically increased simulation times."
  },
  {
    "topic": "Annual Climate-Based Metrics: sDA, UDI, and ASE",
    "content": "After an annual simulation, the raw time-series data is processed to calculate standard climate-based metrics. Key metrics include: Spatial Daylight Autonomy (sDA), the percentage of floor area receiving sufficient daylight (e.g., >300 lux for 50% of occupied hours); Useful Daylight Illuminance (UDI), the percentage of time a point is within a useful illuminance range; and Annual Sunlight Exposure (ASE), the percentage of floor area receiving excessive direct sunlight (e.g., >1000 lux for 250 hours). Calculating ASE accurately requires that the input illuminance data comes from a simulation that correctly models direct sun, making the Five-Phase Method the procedurally correct choice."
  },

{
    "topic": "Radiance Program: gensky",
    "content": "The `gensky` program generates a Radiance description for a standard CIE sky for a specific geographic location, date, and time. Its output is a .rad file that defines the sun and sky as light sources. Key command-line flags include `-c` for a standard CIE overcast sky, and `-B` to set the sky's brightness based on a specified horizontal irradiance, which is essential for Daylight Factor calculations."
  },
  {
    "topic": "Radiance Program: oconv",
    "content": "`oconv` is the Radiance scene compiler. It takes all the individual text-based description files for geometry, materials, and the sky, and compiles them into a single, optimized binary file called an octree (.oct). This octree is a spatial data structure that makes the subsequent ray-tracing process computationally efficient and is a required input for rendering programs like `rpict` and `rtrace`."
  },
  {
    "topic": "Radiance Program: rtrace",
    "content": "`rtrace` is the core command-line calculation engine for quantitative analysis. It traces rays from a set of input points and calculates the light arriving there. When used with the `-I` switch, it computes irradiance (W/m²) at the points specified in an input file, which is the fundamental step for grid-based illuminance simulations."
  },
  {
    "topic": "Radiance Program: rcalc",
    "content": "`rcalc` is a command-line calculator that processes numerical data streams. In lighting simulations, its primary role is to post-process the raw RGB irradiance output from `rtrace`. It applies an expression using the standard luminous efficacy for daylight (179 lm/W) and CIE photopic weighting factors to convert the three-channel radiometric values into a single photopic illuminance value in lux."
  },
  {
    "topic": "Radiance Program: rpict",
    "content": "`rpict` is Radiance's primary tool for generating high-quality, physically-based 2D High-Dynamic-Range (HDR) images from a scene octree. For visual comfort analysis, it's used to render the mandatory 180° hemispherical fisheye image required by the `evalglare` program. This requires specific view parameters: `-vth` for the view type, along with `-vh 180` and `-vv 180` for the view angles."
  },
  {
    "topic": "Radiance Program: evalglare",
    "content": "`evalglare` is a specialized post-processing program that analyzes a 180° fisheye HDR image to calculate Daylight Glare Probability (DGP). It identifies potential glare sources within the image and computes the metric based on their luminance, size, and position, as well as the overall scene brightness. Key options include `-d` for detailed output and `-c` to create a 'check file' image that visually highlights the identified glare sources for verification."
  },
  {
    "topic": "rpict View Types (-vt)",
    "content": "The `rpict` program supports several camera projection models via the `-vt` option, each suited for different tasks. Common types include: `-vtv` (Perspective) for standard, realistic architectural visualizations; `-vtl` (Parallel) for orthographic views like plans and elevations; and `-vth` (Hemispherical Fisheye), which creates an equidistant projection of a 180° hemisphere and is a mandatory format for running a DGP analysis with `evalglare`."
  },
  {
    "topic": "Post-Processing Annual Metrics with Python",
    "content": "After an annual simulation, the raw output file (e.g., .ill) contains 8760 hourly values for each sensor point[. A Python script using libraries like `numpy` and `pandas` is used to derive meaningful metrics. The script reads the binary data, reshapes it into an 8760xN array, filters for an occupied schedule (e.g., weekdays 8am-6pm), and then calculates metrics like sDA, UDI, and ASE by comparing the hourly illuminance values against specified thresholds."
  },
  {
    "topic": "Full Point-in-Time Illuminance Workflow Steps",
    "content": "A complete point-in-time illuminance simulation follows a four-step scriptable workflow. 1. **Generate Sky**: Use `gensky` to create the sky description for the specific time and location. 2. **Create Octree**: Compile all geometry, material, and sky files into a .oct file with `oconv`. 3. **Generate Grid**: Create a sensor points file (.pts) defining the analysis locations. 4. **Run Calculation**: Use `rtrace` with the `-I` flag to compute irradiance at the grid points, then pipe the output to `rcalc` to convert the results to lux."
  },
  {
    "topic": "Full DGP Workflow Steps",
    "content": "A complete Daylight Glare Probability (DGP) analysis is a multi-step process. 1. **Generate Sky**: Create the sky for the desired analysis time with `gensky`. 2. **Create Octree**: Compile the scene into a .oct file with `oconv`. 3. **Render Image**: Use `rpict` with high-quality ambient parameters and a mandatory 180° fisheye view (`-vth -vh 180 -vv 180`) to generate an HDR image. 4. **Calculate DGP**: Process the resulting HDR image with `evalglare` to get the final DGP value and an optional check image."
  },
  {
    "topic": "Full Daylight Factor Workflow Steps",
    "content": "The Daylight Factor (DF) workflow is a five-step process. 1. **Generate Sky**: Use `gensky` with the `-c` and `-B` flags to create a standard CIE Overcast Sky with a known reference horizontal illuminance (e.g., 10,000 lux). 2. **Create Octree**: Compile the scene with `oconv`. 3. **Generate Grid**: Define the analysis points in a .pts file. 4. **Calculate Illuminance**: Use `rtrace` to find the interior illuminance values under the overcast sky. 5. **Calculate DF**: Use `rcalc` to process the results, dividing the interior illuminance by the exterior reference illuminance and multiplying by 100 to get a percentage."
  },
  {
    "topic": "3PM: Matrix Generation Workflow",
    "content": "The Three-Phase Method workflow is split into two parts. The first is the computationally intensive, one-time generation of the View (V) and Daylight (D) matrices. This step is performed with `rcontrib` using high-quality ambient parameters, as any errors are 'baked in' to all subsequent results. It requires separate octrees for the building's interior and exterior to trace light paths from the sensors to the window and from the window to the sky, respectively."
  },
  {
    "topic": "3PM: Annual Calculation Workflow",
    "content": "The second part of the Three-Phase Method is the rapid annual calculation, which leverages the pre-computed matrices. This script first generates an annual sky matrix (.smx) from a weather file using `epw2wea` and `gendaymtx`. Then, the `dctimestep` program performs the final, fast matrix multiplication, combining the V, T (a swappable BSDF file), D, and S matrices to produce the 8760 hourly illuminance results."
  },
  {
    "topic": "5PM: 'Black' Octree for Direct Calculation",
    "content": "The Five-Phase Method requires isolating the direct-sun-only portion of the 3-Phase result for its corrective calculation. To do this, special 'direct-only' matrices (`Vd`, `Dd`) are generated. These matrices are calculated using a special octree where all non-source surfaces in the scene are defined with a perfect black, non-reflective material. This ensures that `rcontrib` only calculates the direct, un-reflected light paths from the sky to the sensors, a crucial step for the subtraction part of the 5PM equation."
  },
  {
    "topic": "5PM: High-Resolution Sun Calculation (Cds Matrix)",
    "content": "To calculate the accurate direct solar component (`I_5PM_direct`), the Five-Phase Method uses a new, high-resolution technique that bypasses the coarse sky patch model of the 3PM. This involves generating a Direct Sun Coefficient matrix (`Cds`). This matrix is calculated with `rcontrib` using a special octree that contains a file with many explicit sun sources (`suns.rad`) and uses a high-resolution tensor tree BSDF for the fenestration. This matrix directly relates the sun's position to the interior sensors with high fidelity."
  },
  {
    "topic": "Three-Phase Radiance Simulation",
    "content": "The Three-Phase Method (3PM) is a matrix-based approach for annual daylight simulations that offers significant flexibility for analyzing complex fenestration systems. It decouples the path of light from the sky to an interior sensor point into three distinct, pre-calculated stages, represented by matrices:\n- D (Daylight Matrix): Characterizes the light transport from the sky patches to the exterior of the fenestration. It is calculated using `rcontrib` with an octree of the building's exterior.\n- T (Transmission Matrix): Describes the optical behavior of the fenestration system itself. This is represented by a Bidirectional Scattering Distribution Function (BSDF), typically an XML file generated with `genBSDF` or LBNL WINDOW.\n- V (View Matrix): Characterizes the light transport from the interior surface of the fenestration to the final sensor points inside the room. It is calculated with `rcontrib` using an interior-only octree.\nFor a full annual simulation, a fourth matrix, S (Sky Matrix), is generated from a climate file using `gendaymtx`. The final illuminance (I) is calculated with a rapid matrix multiplication using the `dctimestep` program: I = V * T * D * S. The primary advantage is that a designer can test different window systems by simply swapping the T matrix (the BSDF file) without re-running the time-consuming V and D matrix calculations."
  },
  {
    "topic": "Spatial Daylight Autonomy and Annual Sunlight Exposure",
    "content": "Spatial Daylight Autonomy (sDA) and Annual Sunlight Exposure (ASE) are two key metrics used in climate-based daylight modeling to evaluate the performance of a building's design.\n\n- sDA (Spatial Daylight Autonomy): This metric measures the sufficiency of ambient daylight in a space. It is formally defined as the percentage of the floor area that meets a minimum illuminance level for a specified fraction of the operating hours per year. A common threshold is the percentage of area that receives at least 300 lux for at least 50% of the occupied hours (e.g., 8 AM to 6 PM).\n\n- ASE (Annual Sunlight Exposure): This metric measures the potential for visual discomfort and excessive solar gain from direct sunlight. It is defined as the percentage of floor area that exceeds a specified illuminance level for a certain number of hours per year. A common threshold is the percentage of area receiving at least 1000 lux of direct sunlight for more than 250 occupied hours. Due to its reliance on the accurate modeling of direct sun, the Five-Phase Method is the procedurally correct way to generate the illuminance data used to calculate ASE."
  },
  {
    "topic": "Radiance Artificial Lighting Simulation",
    "content": "Simulating artificial lighting in Radiance is primarily handled by converting manufacturers' photometric data into a format Radiance can use. This workflow centers on the `ies2rad` command-line utility.\n\n1.  **Data Conversion**: The `ies2rad` program takes a standard IES LM-63 photometric file (.ies) as input. It generates two output files: a Radiance scene description (`.rad`) and a data file (`.dat`). The .rad file contains the luminaire geometry and an `illum` material primitive, which references the .dat file where the interpolated photometric data is stored.\n\n2.  **Integration**: The generated luminaire is placed into a master scene file using the `!xform` command. This allows the luminaire to be translated, rotated, and scaled into its correct position. Because the luminaire is now a self-contained `.rad` file, it can be instanced multiple times to create complex layouts efficiently.\n\n**Best Practices**:\n- **Units**: Ensure consistency between the units used in the `ies2rad` command (e.g., `-d m` for meters) and the units used to model the main scene geometry. A mismatch is a common source of major errors.\n- **Color**: IES files do not contain color information. To ensure color consistency, it is best practice to use the options `-t default -c 1 1 1` with `ies2rad`. This forces a neutral white light output, allowing for color temperature adjustments to be made globally during post-processing."
  },
  {
    "topic": "Five-Phase Radiance Simulation",
    "content": "The Five-Phase Method (5PM) is an advanced annual simulation technique that extends the Three-Phase Method to provide a more accurate calculation of the direct solar component. This is critical for metrics like Annual Sunlight Exposure (ASE) and for analyzing complex, light-redirecting fenestration systems.\n\nThe method is a corrective process based on the following equation:\n`I_5PM = I_3PM_total - I_3PM_direct + I_5PM_direct`\n\nThis involves calculating three separate illuminance time-series:\n1.  **I_3PM_total**: The standard result from a Three-Phase simulation, which accurately models diffuse light but can 'smear' the sun's contribution across a large sky patch.\n2.  **I_3PM_direct**: The inaccurate direct-sun-only portion of the 3PM result. This is calculated using special 'black' octrees (where all surfaces are non-reflective) to isolate only the direct light paths.\n3.  **I_5PM_direct**: A new, high-fidelity direct-sun-only portion. This is calculated using a high-resolution method that bypasses the coarse sky patches, typically involving an octree with many explicit sun sources and a high-resolution 'tensor tree' BSDF for the fenestration.\n\nThe final result is assembled by combining these three components using tools like `rlam` and `rcalc`. The process is more computationally complex than the 3PM but yields the most accurate results for annual simulations where direct sun is a primary concern."
  },
  {
    "topic": "Radiance Simulation Workflows",
    "content": "A typical Radiance simulation, whether for a simple image or a complex annual analysis, follows a general multi-stage workflow from scene creation to final results. While often automated by wrapper tools like Ladybug/Honeybee, understanding the underlying command-line process is key.\n\n1.  **Scene Preparation & Asset Generation**: The user creates text-based files describing the scene. This includes geometry (`.rad` files), material properties (`.mat` or `.rad` files), and sensor point locations (`.pts` file). For annual simulations, a climate file (`.epw`) is used.\n\n2.  **Sky and Light Source Generation**: A sky description is created for a specific time and location using `gensky`. For annual simulations, `gendaymtx` processes a weather file to create an annual sky matrix. Artificial lights are integrated using `ies2rad`.\n\n3.  **Scene Compilation (Octree Generation)**: The `oconv` program compiles all the text-based geometry, material, and sky files into a single, optimized binary file with a `.oct` extension. This octree is a spatial data structure that makes the ray-tracing process computationally feasible and is a mandatory input for the next step.\n\n4.  **Execution (Ray-tracing)**: A core Radiance program is executed to perform the lighting calculation. This is typically `rpict` for rendering an image, `rtrace` for calculating illuminance at specific points, or `rcontrib` for matrix-based calculations.\n\n5.  **Post-Processing & Analysis**: The raw output from the simulation is processed into human-readable metrics. This can involve `rcalc` to convert RGB irradiance to illuminance (lux), `evalglare` to calculate Daylight Glare Probability from an HDR image, or custom scripts (e.g., in Python) to calculate annual metrics like sDA and ASE from time-series data."
  },
  {
    "topic": "Spatial Daylight Autonomy (sDA) Explained",
    "content": "Spatial Daylight Autonomy (sDA) is a climate-based annual metric that quantifies daylight sufficiency. It describes the percentage of a space's regularly occupied floor area that receives a target illuminance level for a specified percentage of occupied hours. The standard reporting format is sDA300,50%, meaning the percentage of floor area that meets or exceeds 300 lux for at least 50% of the occupied hours (typically 8 am to 6 pm). It provides a dynamic assessment of how much of a space is adequately daylit throughout the year."
  },
  {
    "topic": "Annual Sunlight Exposure (ASE) Explained",
    "content": "Annual Sunlight Exposure (ASE) is a metric designed to quantify the potential for visual discomfort and undesirable solar heat gain from excessive direct sunlight. It measures the percentage of a space's floor area that exceeds a specific direct sunlight illuminance threshold for a set number of hours per year. The standard format is ASE1000,250h, representing the percentage of floor area exposed to more than 1000 lux of direct sunlight (from the solar disc only) for more than 250 occupied hours. A high ASE value indicates a significant risk of glare."
  },
  {
    "topic": "ASE vs. sDA: Shading Assumptions",
    "content": "A critical methodological difference exists between ASE and sDA calculations. ASE must be calculated assuming any dynamic shading systems (like operable blinds) are fully open for the entire year. This provides a 'worst-case' assessment of the building's passive design. In contrast, the sDA calculation explicitly models the operation of these shading systems, assuming they are closed when direct sun becomes excessive. This asymmetry intentionally prioritizes good passive design; a high ASE score will force more blind closures, which in turn will lower the sDA score."
  },
  {
    "topic": "Dynamic Shading Logic in sDA Calculations",
    "content": "The IES LM-83 standard mandates the simulation of occupant behavior by modeling dynamic blind operation for sDA calculations. The standard algorithm is deterministic: for any given hour, if more than a specified percentage of the analysis area (e.g., 2%) receives more than 1000 lux of direct-only sunlight, the blinds are considered closed for that hour. This provides a computable proxy for an occupant's response to glare, making sDA a more realistic predictor of real-world performance than a purely static simulation."
  },
  {
    "topic": "Blind Schedule Generation Workflow",
    "content": "Generating the hourly blind operation schedule is a critical pre-processing step for the final sDA calculation. The workflow is as follows: 1. Run an annual simulation that calculates illuminance at each sensor point from direct sun only, assuming blinds are always open. 2. A script iterates through each occupied hour, counting the number of sensor points exceeding 1000 lux. 3. If the percentage of points exceeding the threshold is greater than the trigger value (e.g., 2%), that hour is recorded as 'blinds closed' in a schedule file; otherwise, it's 'blinds open'. This creates a complete annual operation schedule."
  },
  {
    "topic": "3-Phase Method Matrix Components (VMX, TMX, DMX)",
    "content": "The 3-Phase Method decouples the light path into three independently calculated matrices: 1. View Matrix (VMX): Describes the flux transfer from the interior face of the fenestration to the analysis points inside the space. 2. Transmission Matrix (TMX): Describes the flux transfer through the fenestration assembly itself, represented by a BSDF file. 3. Daylight Matrix (DMX): Describes the flux transfer from the sky dome to the exterior face of the fenestration. This modularity allows for rapid testing of different glazing options (swapping the TMX) without re-running the time-consuming geometric calculations for the VMX and DMX."
  },
  {
    "topic": "Why 3-Phase Method is Inaccurate for Direct Sun",
    "content": "The primary limitation of the 3-Phase Method is its handling of direct sun. It uses a sky division (e.g., 145 Reinhart patches) and averages the sun's intense, directional energy across the entire sky patch in which it is located for a given hour. This 'smearing' of the solar disc softens shadows and, more importantly, loses the directional precision needed to accurately simulate Complex Fenestration Systems (CFS) like light shelves or prismatic glazing, which are designed to interact with sunlight from specific angles. This limitation is what necessitates the more advanced 5-Phase Method."
  },
  {
    "topic": "Assembling the Final sDA Illuminance Data",
    "content": "The final illuminance data for an sDA calculation is assembled by combining the results of two separate annual simulations with the generated blind schedule. The required inputs are: 1. An annual illuminance result file calculated with all blinds open. 2. A second annual illuminance result file calculated with all blinds closed. A script then iterates through every hour for every sensor point. It consults the blind schedule and, for each hour, copies the illuminance value from either the 'blinds open' or 'blinds closed' results file into a final, definitive annual illuminance matrix."
  },
  {
    "topic": "Post-Processing Workflow for sDA and ASE",
    "content": "After all simulations are run, raw annual illuminance data is distilled into the final metrics. For sDA: 1. Calculate per-point Daylight Autonomy (DA) by counting the percentage of occupied hours a point is at or above 300 lux. 2. The final sDA is the percentage of total points whose DA is 50% or greater. For ASE: 1. Using the direct-sun-only results, count the number of hours each point is above 1000 lux. 2. The final ASE is the percentage of total points where this hourly count is greater than 250."
  },
  {
    "topic": "Key Changes in ANSI/IES LM-83-23 Standard",
    "content": "The ANSI/IES LM-83-23 standard introduced key refinements to the daylighting calculation methodology to improve consistency and comparability. Two major changes from the earlier LM-83-12 version are: 1. Standardized Radiance Parameters: It is now recommended to use 6 ambient bounces (-ab 6) and an ambient division parameter of 1000 (-ad 1000) for sDA calculations. 2. Adjusted ASE Threshold: The acceptable threshold for Annual Sunlight Exposure was relaxed. While earlier standards cautioned against ASE exceeding 10%, the newer standard acknowledges that some direct sun can be desirable and considers an ASE of up to 20% acceptable in certain cases."
  },
    {
    "topic": "Daylight Autonomy (DA) as a Precursor to sDA",
    "content": "Before the final Spatial Daylight Autonomy (sDA) metric can be determined for a whole room, a per-point precursor metric, Daylight Autonomy (DA), must be calculated. DA is defined for each individual sensor point on the analysis grid as the percentage of occupied hours that the point meets or exceeds the specified illuminance threshold (e.g., 300 lux). The final sDA value is then a spatial summary of these individual DA results, representing the percentage of points that meet the temporal threshold (e.g., 50% of hours)."
  },
  {
    "topic": "The 5-Phase Method Correction Equation",
    "content": "The 5-Phase Method is a refinement technique that improves upon the 3-Phase Method by explicitly separating and recalculating the direct solar component. The underlying process can be expressed with the equation: I_5ph = I_3ph - I_direct,3ph + I_direct,5ph. This means the final, corrected illuminance (I_5ph) is found by taking the total illuminance from a standard 3-Phase simulation, subtracting the inaccurate direct sun component calculated by that same method, and adding back a new, highly accurate direct sun component calculated with a more precise method."
  },
  {
    "topic": "Choosing Between 3-Phase and 5-Phase Methods",
    "content": "The choice between simulation methods is strategic. The 3-Phase Method is generally sufficient and recommended for early-stage design, parametric studies, and projects with conventional, non-redirecting fenestration (e.g., clear or diffuse glazing). The more computationally intensive 5-Phase Method is justified and preferred for final compliance analysis of projects featuring complex fenestration systems (CFS) like light shelves, prismatic panels, or specular blinds, where the accurate modeling of direct sun is critical to performance."
  },
  {
    "topic": "GUI Tools and the 'Black Box' Problem",
    "content": "While modern GUI-based simulation tools (like ClimateStudio or Ladybug Tools) have automated the complex, multi-step Radiance workflows, this convenience introduces the risk of a 'black box' scenario. Users may not fully understand the default settings, Radiance parameters, and underlying assumptions being used by the software. This can lead to discrepancies in results between platforms and potential misinterpretation if the user is not vigilant about verifying that the tool's settings align with project requirements and standards like IES LM-83."
  },
  {
    "topic": "The Sky Matrix: Full vs. Direct-Only Versions",
    "content": "The LM-83 daylighting simulation workflow requires the generation of two distinct annual sky matrices from the climate weather file. The first is a 'Full Sky Matrix', which contains the luminance values from both the diffuse sky and the direct sun, and is used for the final sDA illuminance calculation. The second is a special 'Direct-Only Sky Matrix', which contains only the contribution from the direct sun with all diffuse sky values set to zero. This direct-only matrix is essential for both the ASE calculation and for generating the hourly blind operation schedule."
  },
  {
    "topic": "Window Groups for Granular Shading Control",
    "content": "For sDA simulations, dividing large window areas into smaller, independently controlled 'window groups' can significantly improve daylight autonomy. A window group is a set of windows assumed to be controlled together (e.g., by a single blind). By allowing different parts of a facade to be shaded independently—for instance, closing blinds on an east-facing window in the morning while leaving north-facing windows unshaded—the simulation can optimize daylight penetration more effectively, leading to a higher sDA score without negatively impacting ASE."
  },
  {
    "topic": "The Role of BSDFs in Simulating Complex Fenestration",
    "content": "The Transmission Matrix (TMX) component of the 3-Phase Method is what allows for the accurate modeling of Complex Fenestration Systems (CFS). This matrix is represented by a Bidirectional Scattering Distribution Function (BSDF) file, which provides a complete, angle-dependent description of how a material assembly transmits and reflects light. While a simple pane of glass has a simple BSDF, systems like venetian blinds, fabric shades, or prismatic panels have highly complex BSDFs. Using a BSDF file allows the simulation to capture this behavior without modeling the detailed geometry of the system itself."
  },
  {
    "topic": "ASE's Focus on the Direct Solar Component",
    "content": "A critical distinction in the Annual Sunlight Exposure (ASE) calculation is that it considers only the illuminance contribution directly from the solar disc. The calculation method explicitly ignores diffuse light from the sky vault and any light that has been inter-reflected within the space. This is a deliberate choice to isolate and quantify the specific condition of having direct, unmitigated sun penetration at a point, which is the primary driver of visual discomfort and glare."
  },
  {
    "topic": "Combining Matrices with the dctimestep Program",
    "content": "In matrix-based Radiance workflows like the 3-Phase and 5-Phase methods, the final step of calculating the hourly illuminance values for the entire year is performed by the 'dctimestep' program. This utility is designed specifically for matrix multiplication. It takes the pre-calculated View (VMX), Transmission (TMX/BSDF), Daylight (DMX), and Sky (SMX) matrices as inputs and combines them to produce a large data file containing the illuminance level for each sensor point for each hour of the year."
  },
  {
    "topic": "Organizing Simulation Files: A Recommended Directory Structure",
    "content": "A well-organized file structure is essential for managing the large number of files in a matrix-based simulation. A logical approach is to separate files by function into distinct directories. A typical structure would include: '/data/' for analysis grid point files (*.pts); '/materials/' for material definitions and BSDF files (*.xml); '/objects/' for scene geometry files (*.rad); and '/wea/' for climate data files (*.epw, *.wea). A master script is then used to call the various Radiance programs, referencing files from these organized locations."
  },
    {
    "topic": "Workflow Phase I: View Matrix (VMX) Generation",
    "content": "The View Matrix (VMX) quantifies the light path from the interior side of the windows to the sensor points. It is generated using the 'rcontrib' command in a reverse ray-tracing process. The calculation uses an octree of the interior scene geometry and traces rays from the sensor points back towards the windows. A function file, typically 'klems_int.cal', is used to discretize the hemisphere of outgoing directions from the window surface according to the Klems basis."
  },
  {
    "topic": "Workflow Phase III: Daylight Matrix (DMX) Generation",
    "content": "The Daylight Matrix (DMX) captures the relationship between the external sky and the outside surface of the windows, accounting for external obstructions. It is generated using 'rcontrib', but in a forward process. The 'genklemsamp' utility generates initial rays originating from the exterior window surface, which are traced outwards towards the sky. The octree for this phase includes the building exterior and any site context. The sky is discretized into patches using a standard like the Reinhart division, specified by a function file like 'reinhart.cal'."
  },
  {
    "topic": "The sDA and ASE Causal Link",
    "content": "The IES LM-83 standard creates a direct causal link between the two metrics to prioritize good passive design. A high Annual Sunlight Exposure (ASE) value indicates a high potential for glare. In the subsequent Spatial Daylight Autonomy (sDA) simulation, this high potential for glare triggers more frequent blind closures according to the standard's occupant behavior model. These frequent closures reduce the amount of available daylight, which in turn lowers the final sDA score. Therefore, poor passive design (high ASE) directly leads to poor daylight performance (low sDA)."
  },
  {
    "topic": "Standard Work Plane Height for sDA/ASE",
    "content": "For Spatial Daylight Autonomy (sDA) and Annual Sunlight Exposure (ASE) calculations, the analysis is performed on a horizontal work plane. The standard typically defines this plane at a height of 30 inches (0.76 meters) above the finished floor. This height is considered representative for most common visual tasks in spaces like offices and classrooms, ensuring that the simulation reflects the illuminance levels where they are most relevant to occupants."
  },
  {
    "topic": "Standard Occupied Hours for sDA/ASE",
    "content": "The annual metrics sDA and ASE are evaluated only during a building's scheduled occupied hours. While this can be adjusted, the standard analysis period typically used for compliance and reporting is from 8:00 am to 6:00 pm daily, for every day of the year. The final metric is calculated based on performance only within this timeframe."
  },
  {
    "topic": "The gendaymtx Utility for Sky Matrix Creation",
    "content": "The 'gendaymtx' utility is a core Radiance program used to generate the annual Sky Matrix (SMX) required for climate-based simulations. It takes a Radiance-compatible weather file (.wea) as input, which is typically converted from a standard EnergyPlus weather file (.epw). The program processes this climate data to generate a matrix containing the luminance values for every sky patch for every hour of the analysis year."
  },
  {
    "topic": "The genBSDF Utility for Transmission Matrix Creation",
    "content": "The 'genBSDF' utility in Radiance is a specialized tool used to generate Bidirectional Scattering Distribution Function (BSDF) files, typically in an XML format. These files act as the Transmission Matrix (TMX) in a 3-Phase simulation. 'genBSDF' can create a BSDF by simulating the detailed optical properties of a geometric model of a complex fenestration system, such as a venetian blind or a prismatic panel, allowing its performance to be accurately captured in the annual simulation without modeling the full geometry in every run."
  },
  {
    "topic": "Design Lesson: The Importance of Passive Shading",
    "content": "Case study analysis of sDA and ASE metrics clearly demonstrates the critical importance of passive solar control strategies. An unshaded design often results in very poor performance, with low daylight autonomy and an unacceptably high risk of glare (high ASE). The single act of adding well-designed fixed exterior shading and light shelves can dramatically improve performance, transforming a poor design into a good one by simultaneously reducing ASE to an acceptable level and more than doubling the sDA score."
  },
  {
    "topic": "Simulation Lesson: Sensitivity of Metrics to Parameters",
    "content": "The sDA and ASE metrics are highly sensitive to the inputs and assumptions of the simulation, not just the physical design. Case studies have shown that changes to non-physical parameters—such as a change in the analysis period (e.g., 8am-6pm vs. 9am-5pm) or an update to a calculation script—can significantly impact the final reported metric values. This reinforces the critical need for practitioners to adhere strictly to a standardized methodology, like that outlined in ANSI/IES LM-83-23, to ensure results are accurate, repeatable, and comparable across different projects and tools."
  },
  {
    "topic": "Klems vs. Reinhart Sky Division",
    "content": "In the 3-Phase Method, different hemispherical discretization schemes are used for different matrices. For the View Matrix (VMX), which describes light leaving the interior window surface, the Klems basis ('klems_int.cal') is used. For the Daylight Matrix (DMX), which describes light arriving at the exterior window surface from the sky, the Reinhart division ('reinhart.cal') is typically used. The Reinhart division is favored for the DMX because it provides finer discretization near the horizon and includes specific patches for accurately capturing the sun's position throughout the year."
  },
    {
    "topic": "Strategic Design: Prioritizing Passive Solar Control",
    "content": "A primary design recommendation derived from the sDA/ASE framework is to prioritize passive strategies first. Designers should use the ASE metric in the earliest project stages to mitigate direct sun exposure through fundamental architectural decisions like building orientation, self-shading massing, optimized window-to-wall ratios, and fixed exterior shading elements like overhangs and fins. A design with a low inherent ASE is the foundation for achieving a high sDA."
  },
  {
    "topic": "Strategic Design: Separating View and Daylighting Glazing",
    "content": "To improve performance through more intelligent control, it is recommended to design fenestration that separates the 'view' portion of the window from the 'daylighting' portion. A common example is using a clerestory window above a main view window. This allows blinds on the lower portion to be closed to control glare for occupants, while the upper portion can remain unshaded to continue admitting diffuse daylight deep into the space, thus improving the overall daylight autonomy."
  },
  {
    "topic": "Professional Practice: Understanding Simulation Tool Assumptions",
    "content": "Whether using a custom script or commercial software, it is the designer's responsibility to understand the assumptions and parameters of the simulation. Software should not be treated as an infallible 'black box'. Practitioners must investigate default material properties, Radiance engine settings, and the methodology used for blind operation to ensure they are appropriate for the specific design being analyzed and are in compliance with the latest industry standards."
  },
  {
    "topic": "The 3-Phase Method's Efficiency for Parametric Analysis",
    "content": "The greatest strength of the 3-Phase Method's modularity is the ability to perform rapid and powerful parametric analysis. Because the geometric calculations (VMX and DMX) are decoupled from the fenestration properties (TMX), a designer can explore the impact of changing from double-pane to triple-pane glazing with an integrated blind simply by swapping one BSDF file for another in the final calculation step, without needing to re-run the time-intensive ray-tracing."
  },
  {
    "topic": "Historical Context: Shift from Static to Dynamic Daylight Metrics",
    "content": "The evaluation of daylighting performance has evolved significantly from static, single-point-in-time metrics to dynamic, climate-based annual simulations. This shift, exemplified by the adoption of metrics like sDA and ASE, provides a far more nuanced and realistic prediction of how a building will perform throughout an entire year under varying sky conditions, rather than just at a single moment like the summer solstice."
  },
  {
    "topic": "Limitations of the Standard sDA Blind Operation Model",
    "content": "While including an occupant behavior model is a major step forward, the deterministic blind operation algorithm in the IES LM-83 standard is a pragmatic simplification. It models occupants as perfectly rational automatons who react instantly and uniformly to an illuminance threshold. This behavior is more akin to an automated shading system than the complex, stochastic reality of human interaction. Research suggests the algorithm may be overly aggressive, predicting more frequent blind closures than are typically observed in reality."
  },
  {
    "topic": "The Role of the Master BASH Script in Automation",
    "content": "In a command-line-driven Radiance workflow for sDA and ASE, a master BASH script (e.g., lm83.sh) is used to automate the entire multi-step process. This script is responsible for calling the various Radiance programs (like rcontrib, gendaymtx, dctimestep) in the correct sequence, passing the appropriate input files for each step, and directing the output files to their proper locations within the project's directory structure."
  },
  {
    "topic": "Conceptual Goal of Spatial Daylight Autonomy (sDA)",
    "content": "Spatial Daylight Autonomy (sDA) is an annual, climate-based metric designed to answer the fundamental question: 'How much of the space is adequately daylit for a significant portion of the year?'. Its purpose is to quantify the sufficiency of ambient daylight within a space, using a full year of hourly weather data to provide a dynamic assessment of performance."
  },
  {
    "topic": "Conceptual Goal of Annual Sunlight Exposure (ASE)",
    "content": "While sDA quantifies useful daylight, Annual Sunlight Exposure (ASE) was developed to quantify its negative consequences. Its purpose is to identify areas within a space that are prone to excessive direct sunlight. By doing so, it acts as a proxy metric for the potential risk of significant visual discomfort (glare) and undesirable solar heat gain, which can increase a building's cooling loads."
  },
  {
    "topic": "The rcontrib Command for Matrix Generation",
    "content": "The 'rcontrib' command is the core Radiance program used to generate the coefficient matrices for matrix-based daylighting methods. It is used to generate the View Matrix (VMX) by tracing rays from sensor points back to the windows. It is also used to generate the Daylight Matrix (DMX) by tracing rays from the exterior window surface out towards the sky. In both cases, it calculates the light transfer relationships and stores them in the respective output matrix file."
  },
    {
    "topic": "Four Pillars of BS EN 17037",
    "content": "The European standard BS EN 17037 provides a unified framework for evaluating daylight quality based on four foundational pillars. These pillars, which together define a high-quality daylit environment, are: Daylight Provision, View Out, Exposure to Sunlight, and Protection from Glare."
  },
  {
    "topic": "EN 17037 Performance Levels",
    "content": "BS EN 17037 moves away from prescriptive rules towards performance-based outcomes by establishing three distinct levels of recommendation for daylighting quality: Minimum, Medium, and High. This allows designers to target specific ambitions tailored to the function of the space."
  },
  {
    "topic": "Daylight Provision (Method 2) Dual Criteria",
    "content": "The climate-based method for daylight provision requires satisfying two conditions simultaneously for at least 50% of daylight hours. For the 'Minimum' level, a target illuminance of 300 lux must be met over 50% of the reference plane, and a minimum target illuminance of 100 lux must be met over 95% of the plane to ensure no excessively dark areas."
  },
  {
    "topic": "EN 17037 Definition of 'Daylight Hours'",
    "content": "A crucial part of the EN 17037 methodology is its specific definition of 'daylight hours' for the annual analysis. It is not simply the time between sunrise and sunset. Instead, it is defined as the 4380 hours of the year that have the highest values of diffuse horizontal illuminance, as determined from the site's climate file. This approach prioritizes hours with significant available daylight from the sky."
  },
  {
    "topic": "Daylight Factor Alternative (Method 1)",
    "content": "For early-stage design, the standard provides a simpler alternative to the climate-based method based on the Daylight Factor (DF). Instead of a fixed target, the required DF values are calculated based on the standard's target illuminances and the median external diffuse horizontal illuminance for the specific project location, which is provided in a table within the standard. This method is simpler but less accurate as it is independent of orientation and does not account for direct sunlight."
  },
  {
    "topic": "Sunlight Exposure: Reference Point and Solar Altitude",
    "content": "The assessment for sunlight exposure is not performed on a grid but at a single, precisely defined Reference Point (P) located on the inner surface of the window glazing. A critical constraint is that sunlight hours are only counted when the sun is above a minimum solar altitude angle, which varies with latitude to account for the lower intensity of low-angle sun."
  },
  {
    "topic": "View Out: The Three Criteria (Angle, Distance, Layers)",
    "content": "To assess the quality of a view, three criteria must be met simultaneously: Horizontal Sight Angle, Outside Distance of View, and the Number of Layers visible. The 'Horizontal Sight Angle' measures the view's width. The 'Outside Distance' measures the depth to the nearest obstruction. The view must also contain a specific number of layers from the three defined categories: Sky, Landscape, and Ground."
  },
  {
    "topic": "Glare Protection: Annual DGP Exceedance",
    "content": "The standard uses Daylight Glare Probability (DGP) as its core metric for discomfort glare. The compliance check is temporal: the calculated DGP value must not exceed a specified threshold for more than 5% of the reference usage time. The DGP thresholds vary by performance level, with a value of ≤0.40 for 'Medium' and ≤0.35 for 'High'."
  },
  {
    "topic": "EN 17037 Standard Material Reflectance Values",
    "content": "For compliance simulations where specific material data is unavailable, BS EN 17037 Annex B.3.1 provides recommended reflectance ranges to be used as a baseline. These are: Ceiling: 0.7 to 0.9, Walls: 0.5 to 0.8, Floor: 0.2 to 0.4, and Exterior Ground: 0.2. Using these values ensures consistency between assessments."
  },
  {
    "topic": "EN 17037 Analysis Grid Specifications",
    "content": "The standard provides clear specifications for the analysis grid in Annex B.2. The reference plane for calculations is located 0.85 m above the finished floor. The grid must also exclude a peripheral band of 0.5 m from the walls. The standard gives a formula to determine the maximum grid cell size based on the longer dimension of the space, ensuring appropriate resolution."
  },
  {
    "topic": "The Compounding Effect of Material Reflectance Errors",
    "content": "In a ray-tracing simulation, a small initial error in an assumed material reflectance value is not static; it is compounded with every subsequent light bounce. The -ab (ambient bounces) parameter controls how many times light reflects within a space. [Each bounce multiplies the light's energy by the surface reflectance. Consequently, an initial 5% error in wall reflectance can become a much larger error in the final calculated illuminance deep within a room."
  },
  {
    "topic": "Using Angular Fisheye Projections for View Out Analysis",
   "content": "The advanced verification method for the 'View Out' criterion requires creating an equidistant fisheye projection of the view. In Radiance, this is achieved by using the rpict command with the view type flag set to 'a' for angular fisheye (-vta). This projection maps the angle from the central view direction linearly to the radial distance in the image, matching the specification in the standard. A full hemispherical view is also required, meaning the horizontal (-vh) and vertical (-vv) fields of view must be set to 180 degrees."
  },
  {
    "topic": "Automated Workflow for Annual Glare (DGP) Simulation",
    "content": "An annual glare analysis is only feasible with significant automation, typically using a script. The workflow involves: 1. Defining the occupied hours for the year. 2. Looping through each occupied hour. 3. Inside the loop, calling 'gensky' to generate the sky for that specific moment. 4. Calling 'rpict' to render a fisheye HDR luminance image. 5. Calling 'evalglare' to process the image and calculate the DGP value. 6. Parsing the output to log the DGP value with its timestamp."
  },
  {
    "topic": "The Criticality of Modeling External Context",
    "content": "A building's access to daylight is directly influenced by its surroundings, so the simulation model must include all significant external obstructions like adjacent buildings, landforms, and dense vegetation. Failing to model the urban or natural context will lead to a gross overestimation of daylight availability and render the simulation results invalid for compliance purposes. The context model should extend far enough to capture all objects that subtend a significant angle from the windows being analyzed."
  },
  {
    "topic": "Modeling Internal Detail for High-Fidelity Simulation",
    "content": "For a high-fidelity simulation, the model should include internal elements beyond the main room surfaces. Internal partitions, columns, soffits, and large furniture can cast shadows and create secondary reflective surfaces that alter illuminance patterns. Furthermore, the thickness of walls and the depth of window reveals are critical, as they define the 'tunnel' through which daylight must pass and can significantly reduce the amount of sky visible from interior points."
  },
  {
    "topic": "Visual Verification of Sunlight Exposure with Sun-Path Diagrams",
    "content": "A powerful method for validating and communicating sunlight exposure results is to overlay a sun-path diagram onto a fisheye rendering of the view from the reference point. The sun's path for the chosen analysis day can be traced across the image. Portions of the path that fall on the sky represent periods of potential sunlight, while portions that fall on buildings or other obstructions represent periods of shadow. This provides an intuitive and compelling visual confirmation of the numerical simulation results."
  },
  {
    "topic": "Identifying View Layers Using Distinct Materials",
    "content": "To programmatically assess the 'Number of Layers' criterion for View Out, external surfaces in the simulation scene must be assigned distinct materials that can be identified later. For example, the sky can be assigned a 'skyfunc' modifier, the ground plane a 'ground_material', and all context buildings and landscape elements a 'landscape_material'. By analyzing the pixels within the rendered view opening, a script can then determine the presence of each layer."
  },
  {
    "topic": "Direct-Only Ray-Tracing for Sunlight Exposure Check",
    "content": "To check for an unobstructed line of sight to the sun for the Sunlight Exposure criterion, a direct-only ray-tracing calculation is used. The 'rtrace' command is configured to isolate only the direct contribution from the sun by setting ambient bounces to zero (-ab 0) and disabling direct source subdivision and jittering (-ds 0, -dt 0, -dc 0). A non-zero result indicates an unobstructed path from the sun to the reference point at that time."
  },
  {
    "topic": "Understanding the Daylight Glare Probability (DGP) Formula",
    "content": "Daylight Glare Probability (DGP) is an empirical index that predicts the percentage of people disturbed by glare in a scene. The formula incorporates both the overall adaptation level of the eye, which is driven by the vertical illuminance at the eye (Ev), and the contrast effect of individual bright sources. The effect of each glare source is determined by its luminance (Ls,i), its solid angle (ωs,i), and its position index (Pi) relative to the occupant's line of sight."
  },
  {
    "topic": "The 'evalglare' Utility for DGP Calculation",
    "content": "The 'evalglare' program is the dedicated Radiance utility for post-processing High Dynamic Range (HDR) fisheye images to calculate glare indices. It takes a 180° fisheye luminance image as input, automatically identifies potential glare sources based on their brightness, and calculates the Daylight Glare Probability (DGP) value. Using the '-v' (verbose) flag in the command will produce a text output that includes the final calculated DGP value."
  },
  {
    "topic": "Introduction to EN 12464-1 and Radiance",
    "content": {
      "standard_overview": {
        "title": "EN 12464-1: A Performance-Based Standard",
        "description": "The European Standard EN 12464-1, 'Light and lighting – Lighting of work places – Part 1: Indoor work places,' is a performance-based document. Instead of prescribing specific technologies or layouts, it specifies the required outcomes for a luminous environment. Its core philosophy is to satisfy three basic human needs: visual comfort, visual performance, and safety."
      },
      "key_criteria": [
        {
          "name": "Luminance Distribution",
          "description": "The balance of brightness on all surfaces within the field of view, which controls eye adaptation and affects visual comfort."
        },
        {
          "name": "Illuminance",
          "description": "The amount of light falling on the task area and its immediate surroundings, specified as a maintained value (Em)."
        },
        {
          "name": "Glare",
          "description": "The limitation of excessive brightness that can cause discomfort or disability, quantified by the Unified Glare Rating (UGR)."
        },
        {
          "name": "Directionality of Light",
          "description": "The interplay of diffuse and directional light, which affects the modeling of objects and the revelation of texture and form."
        },
        {
          "name": "Colour Aspects",
          "description": "The colour appearance (Correlated Colour Temperature, TCP) and colour rendering (Colour Rendering Index, Ra) of the light source."
        },
        {
          "name": "Daylight",
          "description": "The integration and control of natural light to supplement or replace artificial lighting."
        }
      ],
      "radiance_overview": {
        "title": "Radiance: A Physically-Based Simulation Engine",
        "description": "Radiance is a suite of over 50 command-line tools for the analysis and visualization of lighting. Its primary advantage is its rigorous adherence to the physical principles of light transport, allowing it to calculate physically accurate lighting values. Its core methodology is a hybrid deterministic and stochastic backward ray-tracing algorithm, tracing rays from a sensor back into the scene until they terminate at a light source."
      },
      "fundamental_quantity": {
        "title": "Spectral Radiance as the Core Calculation",
        "description": "The fundamental physical quantity calculated by Radiance is spectral radiance (W⋅sr⁻¹⋅m⁻²). All other photometric quantities are mathematically derived from this unit. For example, Luminance (cd⋅m⁻²) is the photopic (human eye-weighted) equivalent of radiance, and Illuminance (lux) is the integral of luminance over a hemisphere. This ensures that all analyses are internally consistent and physically correct."
      }
    }
  },
  {
    "topic": "Scene Preparation for Simulation (The Digital Twin)",
    "content": {
      "geometric_fidelity": {
        "title": "Creating the 3D Scene Geometry",
        "source": "Most architectural projects originate in CAD or BIM software such as Revit, Rhino, or SketchUp.",
        "best_practices": [
          "Model Simplification: Architectural models should be simplified to represent the primary light-interacting surfaces, as excessive detail significantly increases computation time with little gain in accuracy.",
          "Watertight Volumes: All enclosed spaces should be modeled as 'watertight' or closed volumes to prevent light leaks.",
          "Correct Surface Normals: All polygons must have their surface normals oriented correctly (pointing outwards from a solid or into an enclosed space)."
        ],
        "radiance_tools": {
          "tool": "genbox",
          "description": "For basic scenes, Radiance's own generator programs like 'genbox' are highly efficient.",
          "example_command": "genbox room_material room_name 5 8 3 -i > room.rad",
          "notes": "The -i flag inverts the surface normals to point inwards, which is correct for an interior scene."
        }
      },
      "surface_properties": {
        "title": "Defining Surface Reflectance and Materiality",
        "en12464_reflectance_ranges": {
          "Ceiling": "0.6 to 0.9",
          "Walls": "0.3 to 0.8",
          "Working Planes": "0.2 to 0.6",
          "Floor": "0.1 to 0.5"
        },
        "radiance_materials": [
          {
            "type": "plastic",
            "description": "The most common material type, used for matte or semi-glossy opaque surfaces. It models both a diffuse color component and a specular (highlight) component. The specular reflections are uncolored.",
            "syntax": "void plastic material_name\n0\n0\n5 red_reflectance green_reflectance blue_reflectance specularity roughness"
          },
          {
            "type": "metal",
            "description": "Used for metallic surfaces. The key difference from 'plastic' is that its specular highlights are colored by the material's base color."
          }
        ]
      },
      "light_source_modeling": {
        "title": "Modeling Artificial and Natural Light",
        "artificial_lighting": {
          "process": "Luminaires are characterized by IES photometric files (.ies). The 'ies2rad' utility converts these files into a Radiance scene description. The 'xform' utility is then used to translate (-t), rotate (-r), and scale (-s) the luminaire into its correct position in the 3D scene.",
          "example_ies2rad": "ies2rad -p lum_subdir -l /path/to/library my_luminaire.ies",
          "example_xform": "!xform -t 2.5 4 2.8 /path/to/library/lum_subdir/my_luminaire.rad"
        },
        "daylighting": {
          "point_in_time_analysis": "For specific moments, the 'gensky' program is used. It generates a description of a CIE standard sky (e.g., overcast, clear) for a given date, time, and location.",
          "annual_climate_based_simulation": "For year-long analysis, a matrix-based method is used. The 'gendaymtx' program uses an EnergyPlus Weather (EPW) file to generate a sky matrix that describes the radiance of the sky for every hour of the year."
        }
      },
      "scene_compilation": {
        "title": "Creating the Octree",
        "description": "The final step is to compile all individual text-based .rad files (geometry, materials, lights) into a single, highly optimized binary file called an octree (.oct). The octree is a spatial data structure that dramatically accelerates ray-tracing.",
        "command": "The 'oconv' command performs this compilation.",
        "example_command": "oconv materials.rad room.rad furniture.rad luminaires.rad sky.rad > scene.oct"
      }
    }
  },
  {
    "topic": "Quantitative Analysis: Verifying Illuminance and Uniformity",
    "content": {
      "maintenance_factor": {
        "title": "Applying the Maintenance Factor (MF)",
        "concept": "EN 12464-1 specifies 'maintained illuminance', the value below which the average illuminance should not fall. Radiance simulates the initial, 'day one' state. The MF must be applied to the simulation inputs to account for light loss over the installation's life.",
        "formula": "MF = LLMF × LSF × LMF × RSMF",
        "components": [
          {
            "name": "LLMF (Lamp Lumen Maintenance Factor)",
            "description": "Represents the depreciation of the light source's output over time."
          },
          {
            "name": "LSF (Lamp Survival Factor)",
            "description": "Represents the percentage of lamps expected to still be operational."
          },
          {
            "name": "LMF (Luminaire Maintenance Factor)",
            "description": "Accounts for dirt accumulation on the luminaire's optical surfaces."
          },
          {
            "name": "RSMF (Room Surface Maintenance Factor)",
            "description": "Accounts for the reduction in surface reflectances due to dirt."
          }
        ],
        "calculation": "The required initial illuminance for the simulation is calculated as: Initial Illuminance = Maintained Illuminance / MF. For example, a 500 lx requirement with an MF of 0.8 means the simulation must achieve an initial 625 lx."
      },
      "calculation_grid": {
        "title": "Defining the Calculation Grid",
        "description": "To measure illuminance, a grid of calculation points is defined in a text file. Separate grids should be used for the 'task area' and the 'immediate surrounding area'.",
        "format": "Each line specifies one point in the format: x_coord y_coord z_coord x_normal y_normal z_normal. For a standard horizontal work plane, the normal vector is always 0 0 1."
      },
      "illuminance_simulation": {
        "title": "Executing the Simulation with rtrace",
        "command": "The core calculation is performed by the 'rtrace' program.",
        "key_flags": [
          {
            "flag": "-I",
            "description": "Switches the calculation from radiance (default) to irradiance/illuminance."
          },
          {
            "flag": "-h",
            "description": "Suppresses header information in the output."
          },
          {
            "flag": "-w",
            "description": "Suppresses common warning messages."
          },
          {
            "flag": "-ab N",
            "description": "Sets the number of ambient bounces (inter-reflections). A value of 5-7 is recommended for compliance to accurately model uniformity."
          },
          {
            "flag": "-lw",
            "description": "Sets the minimum ray weight to prevent premature ray termination, improving accuracy."
          }
        ]
      },
      "post_processing": {
        "title": "Post-Processing and Verification",
        "conversion_to_lux": "The raw radiometric output from 'rtrace' is converted to a single illuminance value in lux using the 'rcalc' utility with the standard CIE luminous efficacy formula.",
        "metric_calculation": "From the final list of lux values, the following metrics are calculated: \n- Average Illuminance (Em): The arithmetic mean of all values.\n- Minimum Illuminance (Emin): The lowest value.\n- Illuminance Uniformity (U0): Calculated as the ratio Emin / Em.",
        "verification": "These calculated values are then directly compared against the requirements listed in the tables of EN 12464-1 for the specific task or area."
      }
    }
  },
  {
    "topic": "Qualitative Analysis: Simulating Glare and Visual Comfort",
    "content": {
      "ugr_workflow": {
        "title": "Unified Glare Rating (UGR) Calculation Workflow",
        "step_1": {
          "name": "Image Generation with rpict",
          "description": "Generate a 180° hemispherical fisheye image from the observer's exact viewpoint. The view type is set with '-vt h', and view angles are set with '-vh 180 -vv 180'."
        },
        "step_2": {
          "name": "Glare Calculation with evalglare",
          "description": "The generated HDR image is processed by the 'evalglare' program. It analyzes the luminance map to automatically identify potential glare sources and computes the UGR value."
        },
        "step_3": {
          "name": "UGR Verification",
          "description": "The single numerical UGR result from 'evalglare' is compared against the Unified Glare Rating Limit (UGRL) specified in EN 12464-1. If the simulated value exceeds the limit, the design is non-compliant."
        }
      },
      "dse_reflections": {
        "title": "Assessing DSE Lighting and Veiling Reflections",
        "methodology": "The DSE screen is modeled as a surface with low diffuse reflectance and a small amount of specularity. A high-quality photorealistic image is generated using 'rpict' from the user's viewpoint. The resulting HDR image is viewed with a tool like 'ximage', where the absolute luminance value of any reflection can be measured by clicking on it.",
        "compliance": "This measured luminance is compared to the limits in EN 12464-1. For example, for good quality screens, the average luminance of any reflected luminaire should be ≤1000 cd⋅m⁻²."
      },
      "directional_lighting": {
        "title": "Visualizing Directional Lighting and Modelling",
        "concept": "'Modelling' is the balance between diffuse and directional light that reveals the form and texture of objects. It is an inherently qualitative criterion.",
        "assessment": "Compliance is assessed through visual inspection of high-quality photorealistic renderings. Placing simple geometric objects, such as a sphere, in the scene provides a clear indication of the lighting's directional qualities by showing how light and shadow render on its form."
      }
    }
  },
  {
    "topic": "Integrating Complex Scenarios and Advanced Criteria",
    "content": {
      "combined_lighting": {
        "title": "Combined Lighting Systems: Daylight and Artificial Light",
        "workflow": "To simulate the combined effect, both the daylight source (from 'gensky' or 'gendaymtx') and the artificial light sources are included in the scene description before compiling a single octree with 'oconv'.",
        "rationale": "This approach is physically more accurate than simulating each system separately and adding the results. It correctly captures the non-linear nature of inter-reflected light, where a bright patch of sunlight, for example, can act as a secondary light source that influences the entire scene and the UGR calculation."
      },
      "color_aspects": {
        "title": "Addressing Colour Aspects: Ra and TCP",
        "radiance_model": "Radiance operates on a physical, radiometric basis and does not inherently calculate perceptual metrics like Colour Rendering Index (Ra) or Correlated Colour Temperature (TCP).",
        "compliance_workflow": "Verification of these criteria is a matter of specification, not a simulation output. The designer must select a luminaire that meets the Ra requirement per manufacturer data, model its color accurately, and state the specified Ra and TCP in the compliance documentation."
      },
      "shadowing_and_flicker": {
        "title": "Simulating Shadowing and Flicker",
        "shadowing": "Radiance's ray-tracing engine is inherently adept at accurately simulating both hard and soft shadows (penumbras). The assessment of shadow quality is qualitative and is done by visually inspecting high-quality renderings.",
        "flicker": "Flicker and stroboscopic effects are temporal phenomena related to the electrical supply. Radiance is a static lighting simulation tool and cannot simulate these time-dependent effects. Compliance is achieved through proper equipment specification, such as using luminaires with high-frequency electronic ballasts."
      }
    }
  },
  {
    "topic": "Conclusion: A Framework for Simulation-Driven Lighting Design",
    "content": {
      "iterative_workflow": {
        "title": "The Iterative Verification Workflow",
        "loop": "The power of the methodology lies in its application as an iterative design tool, summarized as a continuous feedback loop: Model -> Simulate -> Analyze -> Refine.",
        "diagnostic_power": "A simulation failure is not a dead end. The visual and quantitative data provides direct diagnostic information about the cause of non-compliance (e.g., a fisheye image pinpoints the offending luminaire for high UGR), allowing for targeted design modifications."
      },
      "radiance_parameters": {
        "title": "Best Practices for Radiance Parameters",
        "description": "The accuracy of a simulation is highly dependent on 'ambient parameters' that control the indirect illumination calculation. The following settings are recommended for final verification.",
        "parameter_table": [
          {
            "Parameter": "Ambient Bounces",
            "Flag": "-ab",
            "Draft Quality": "2",
            "Compliance Quality": "5 - 7",
            "Description": "Number of diffuse inter-reflections calculated. Higher values are essential for accurate uniformity and background luminance."
          },
          {
            "Parameter": "Ambient Divisions",
            "Flag": "-ad",
            "Draft Quality": "512",
            "Compliance Quality": "1024 - 2048",
            "Description": "Number of sample rays sent for the indirect calculation. Higher values better resolve complex geometry and daylight."
          },
          {
            "Parameter": "Ambient Supersamples",
            "Flag": "-as",
            "Draft Quality": "128",
            "Compliance Quality": "256 - 512",
            "Description": "Number of extra samples in areas of high ambient gradient. Reduces splotchy artifacts."
          },
          {
            "Parameter": "Ambient Resolution",
            "Flag": "-ar",
            "Draft Quality": "64",
            "Compliance Quality": "128 - 256",
            "Description": "Density of the ambient file grid. Controls how finely the indirect cache is stored."
          },
          {
            "Parameter": "Ambient Accuracy",
            "Flag": "-aa",
            "Draft Quality": "0.15",
            "Compliance Quality": "0.1",
            "Description": "Error tolerance for the indirect calculation. Lower values are more accurate but slower."
          },
          {
            "Parameter": "Limit Weight",
            "Flag": "-lw",
            "Draft Quality": "0.005",
            "Compliance Quality": "0.001",
            "Description": "Minimum contribution a ray must have to be traced. Lower values increase accuracy in dark or complex areas."
          }
        ]
      },
      "final_recommendations": {
        "title": "Final Recommendations and Future Outlook",
        "benefits": "A simulation-driven methodology elevates the design process from one based on rules-of-thumb to one grounded in predictive, physical science. This allows for greater design freedom and innovation, as unconventional solutions can be rigorously tested and validated.",
        "future_outlook": "The physically-based nature of Radiance positions it well to address emerging frontiers in lighting design, such as analyzing non-visual lighting effects like circadian stimulus by incorporating new spectral sensitivity functions."
      }
    }
  },
  {
    "topic": "Introduction to BS EN 17037 and Radiance",
    "content": {
      "standard_overview": {
        "title": "BS EN 17037: A New Paradigm of Daylight Design",
        "description": "The European standard BS EN 17037:2018, 'Daylight in buildings', establishes a unified, holistic framework for evaluating the quality of natural light in occupied spaces. It moves beyond simplistic metrics to consider daylighting as a critical component of occupant health, well-being, and building energy efficiency."
      },
      "four_pillars": [
        {
          "name": "Daylight Provision",
          "description": "Ensuring sufficient ambient light levels within a space."
        },
        {
          "name": "View Out",
          "description": "Quantifying the quality of the visual connection to the outdoors."
        },
        {
          "name": "Exposure to Sunlight",
          "description": "Assessing the duration of direct sunlight access."
        },
        {
          "name": "Protection from Glare",
          "description": "Evaluating and mitigating the risk of discomfort from excessive brightness."
        }
      ],
      "performance_levels": {
        "title": "Performance-Based Criteria",
        "description": "The standard introduces three distinct levels of recommendation—Minimum, Medium, and High—empowering designers to target specific ambitions for daylighting quality tailored to the function of the space. This shift towards performance-based outcomes necessitates sophisticated and accurate prediction methods."
      },
      "radiance_overview": {
        "title": "Radiance: The Gold Standard for Simulation",
        "description": "Radiance is a suite of programs widely recognized as the gold-standard engine for lighting simulation. It is a physically-based, backward ray-tracing tool that has been extensively validated. It is not a single program with a GUI, but a collection of powerful command-line utilities (like rpict, rtrace, gensky) that provide unparalleled flexibility and control for calculating illuminance, luminance, and glare."
      },
      "simulation_approach": {
        "title": "Advanced Annual Simulation Methods",
        "description": "The standard's introduction of annual, climate-based metrics makes a brute-force approach of simulating every daylight hour computationally prohibitive. This reality implicitly demands the use of advanced, efficient simulation techniques, such as matrix-based methods, which are the only practical and rigorous approach to demonstrating compliance."
      }
    }
  },
  {
    "topic": "Foundational Simulation Setup",
    "content": {
      "digital_twin_modeling": {
        "title": "The Digital Twin: Modeling for Accuracy",
        "geometric_fidelity": "The 3D digital model, typically from CAD or BIM software, must be a 'watertight' and faithful representation of the architectural design's dimensions, volumes, and spatial relationships.",
        "context_modeling": "The simulation must include all significant external obstructions, such as adjacent buildings, landforms, and dense vegetation. Failing to model the context will lead to a gross overestimation of daylight availability.",
        "internal_detail": "For high-fidelity simulations, internal elements like partitions, columns, and soffits should be included. The thickness of walls and depth of window reveals are critical as they define the 'tunnel' for daylight."
      },
      "material_properties": {
        "title": "Material Properties: The Physics of Light Interaction",
        "radiance_primitives": [
          {
            "type": "plastic",
            "description": "Represents a matte surface with an optional, uncolored specular highlight. Used for most opaque surfaces like painted walls and ceilings."
          },
          {
            "type": "metal",
            "description": "Represents a metallic surface with colored specular highlights."
          },
          {
            "type": "glass",
            "description": "Represents a simple dielectric material like clear glass, defined by its transmissivity and refractive index."
          },
          {
            "type": "trans",
            "description": "A more complex material for translucent or diffuse-scattering materials."
          }
        ],
        "en17037_recommendations": {
          "description": "For compliance simulations where specific material data is not yet available, BS EN 17037 Annex B.3.1 provides recommended reflectance ranges.",
          "values": {
            "Ceiling": "0.7 to 0.9",
            "Walls": "0.5 to 0.8",
            "Floor": "0.2 to 0.4",
            "Exterior Ground": "0.2"
          }
        },
        "importance_of_accuracy": "Errors in assumed reflectance values are compounded with every subsequent light bounce in a ray-tracing simulation (controlled by the -ab parameter). A small initial error can become a much larger error in the final calculated illuminance."
      },
      "climate_data": {
        "title": "Climate and Sky: Defining the Luminous Environment",
        "data_source": "The standard format for climate data is the EnergyPlus Weather (EPW) file, which contains a full year of meteorological data, including Direct Normal Irradiance (DNI) and Diffuse Horizontal Irradiance (DHI).",
        "generation_of_skies": "The 'gendaymtx' command reads an EPW file and outputs a Radiance sky matrix. This matrix contains the luminance values for 145 discrete patches of the Tregenza sky dome for all 8760 hours of the year."
      },
      "analysis_grid": {
        "title": "The Analysis Grid: Establishing Measurement Points",
        "standard_specifications": "BS EN 17037, Annex B.2, specifies that the analysis grid's reference plane is located 0.85 m above the floor and should exclude a peripheral band of 0.5 m from the walls.",
        "grid_resolution_formula": "The maximum grid cell size (p) is determined by the formula: p = 0.5 * 5^log10(d), where d is the longer dimension of the calculation area.",
        "implementation": "The final grid is a text file where each line represents a sensor point with six values: X, Y, Z coordinates followed by the X, Y, Z components of the surface normal vector (e.g., 0 0 1 for horizontal)."
      }
    }
  },
  {
    "topic": "Daylight Provision (Method 2: Climate-Based)",
    "content": {
      "metric_definition": {
        "title": "Deconstructing the Metric",
        "dual_criteria": "Compliance requires satisfying two conditions simultaneously: a Target Illuminance (ET) over a certain percentage of the area, and a Minimum Target Illuminance (ETM) over a larger percentage of the area.",
        "example_minimum_level": "For the 'Minimum' performance level, the target is 300 lux over at least 50% of the plane, AND 100 lux over at least 95% of the plane.",
        "temporal_component": "Both of the spatial criteria must be met for at least half (50%) of the annual 'daylight hours'.",
        "daylight_hours_definition": "'Daylight hours' are defined as the 4380 hours of the year that have the highest values of diffuse horizontal illuminance, as determined from the site's EPW climate file."
      },
      "simulation_workflow": {
        "title": "The Annual Climate-Based Approach using Matrix Methods",
        "three_phase_method": {
          "name": "Three-Phase Method",
          "description": "An efficient matrix-based approach that breaks the path of light into three stages, each represented by a pre-calculated matrix. The final hourly illuminance is calculated rapidly by multiplying these matrices.",
          "components": [
            "Daylight Matrix (D): Light transfer from sky patches to the exterior of windows.",
            "Transmission Matrix (T): How light is transmitted through the fenestration system (can be a complex BSDF).",
            "View Matrix (V): Light transfer from the interior surface of the fenestration to each sensor point, including inter-reflections."
          ],
          "calculation": "The 'dctimestep' program performs the matrix multiplication for all hours: I_hourly = V * T * D * s_hourly."
        },
        "five_phase_method": {
          "name": "Five-Phase Method",
          "description": "An extension of the Three-Phase Method that calculates the contribution from direct sun separately for higher accuracy, often used for Annual Sunlight Exposure (ASE) calculations."
        }
      },
      "post_processing": {
        "title": "Post-Processing and Compliance Verification",
        "data_conversion": "The raw Radiance output is converted into illuminance in lux using the 'rcalc' utility.",
        "scripted_workflow": "Compliance is best checked with an automated script. The script loads the data, identifies the 4380 daylight hours from the EPW file, filters the illuminance results for those hours, and then for each hour, checks if the spatial criteria are met. Finally, it counts the number of passing hours to check if the 50% temporal criterion is met for both ET and ETM."
      },
      "daylight_factor_alternative": {
        "title": "The Daylight Factor Alternative (Method 1)",
        "concept": "A simpler alternative based on the Daylight Factor (DF), calculated using a single simulation under a standard CIE Overcast Sky (generated with 'gensky -c').",
        "target_calculation": "The required target DF is not fixed; it's calculated based on the target illuminance and the median external diffuse horizontal illuminance for the project location. For Athens (median 19,400 lux), the 300 lux target corresponds to a 1.5% target DF.",
        "limitations": "This method is less accurate as it is independent of orientation and does not account for direct sunlight or dynamic sky conditions."
      }
    }
  },
  {
    "topic": "Exposure to Sunlight",
    "content": {
      "metric_definition": {
        "title": "Deconstructing the Metric",
        "requirement": "The space must receive direct, unobstructed sunlight for a minimum duration at a specific reference point.",
        "performance_levels": "Targets are 1.5 hours ('Minimum'), 3.0 hours ('Medium'), and 4.0 hours ('High').",
        "reference_day": "The assessment is conducted on a single day between February 1st and March 21st (the equinox is common).",
        "reference_point_p": "The analysis is done at a single point (P) located on the inner surface of the window glazing, at its horizontal center and 1.2 m above the floor.",
        "minimum_solar_altitude": "Sunlight is only counted when the sun is above a minimum altitude angle, which varies with latitude (e.g., 20° for Athens on March 21st)."
      },
      "simulation_workflow": {
        "title": "Simulation Workflow: Tracing the Sun",
        "sky_generation": "The 'gensky' utility is used with the '+s' flag to generate the sky with a discrete sun source for a specific date and time.",
        "direct_ray_tracing": "The 'rtrace' command is used with ambient bounces set to zero ('-ab 0') to trace a single ray and check for an unobstructed path from the sun's position to the reference point P. A non-zero result means the sun is visible.",
        "automation": "A script iterates through the day in discrete time steps (e.g., every 15 minutes), updating the sun's position with 'gensky' and checking for visibility with 'rtrace'."
      },
      "verification": {
        "title": "Post-Processing and Compliance Verification",
        "summing_hours": "The total duration of sunlight exposure is calculated by summing the length of the time steps during which 'rtrace' returned a non-zero value.",
        "visual_verification": "A powerful validation method is to overlay a sun-path diagram onto a 180° angular fisheye rendering ('rpict -vta') of the view from point P. This provides an intuitive visual confirmation of when the sun's path is obstructed."
      }
    }
  },
  {
    "topic": "View Out",
    "content": {
      "metric_definition": {
        "title": "Deconstructing the Metric",
        "three_criteria": "To achieve a given performance level, a view must satisfy three criteria simultaneously: Horizontal Sight Angle, Outside Distance of View, and Number of Layers.",
        "criteria_details": [
          {
            "name": "Horizontal Sight Angle",
            "targets": "≥14° (Minimum), ≥28° (Medium), ≥54° (High)."
          },
          {
            "name": "Outside Distance of View",
            "targets": "≥6.0 m (Minimum), ≥20.0 m (Medium), ≥50.0 m (High)."
          },
          {
            "name": "Number of Layers",
            "targets": "The view must include a certain number of the three layers (Sky, Landscape, Ground). A 'High' quality view must include all three."
          }
        ]
      },
      "simulation_workflow": {
        "title": "The Advanced Projection Method",
        "fisheye_rendering": "The assessment relies on creating an equidistant fisheye projection of the view from a seated eye height (1.2 m). This is done with the 'rpict' rendering program.",
        "rpict_parameters": "The key view type is angular fisheye ('-vta'). A full hemispherical view is required, so the horizontal ('-vh') and vertical ('-vv') fields of view must be set to 180 degrees."
      },
      "verification": {
        "title": "Post-Processing and Compliance Verification",
        "image_analysis": "The resulting HDR image is analyzed. The horizontal extent of the window opening corresponds to the sight angle. By assigning distinct materials to the sky, landscape, and ground, a script can identify the presence of each layer within the view.",
        "geometric_analysis": "The 'Outside Distance of View' is a geometric measurement, found by casting rays from the viewpoint through the window in the 3D model to find the distance to the first obstruction. This can be done with 'rtrace' or in the CAD environment."
      }
    }
  },
  {
    "topic": "Protection from Glare",
    "content": {
      "metric_definition": {
        "title": "Deconstructing the Metric",
        "core_metric": "The standard uses Daylight Glare Probability (DGP), an index that predicts the percentage of people who would be disturbed by glare. It incorporates both the overall eye adaptation level (vertical illuminance, Ev) and the effect of individual bright sources.",
        "temporal_criterion": "The calculated DGP value must not exceed a specified threshold for more than 5% of the reference usage time (e.g., 08:00 to 18:00 on weekdays).",
        "performance_levels": [
          {
            "level": "Minimum",
            "threshold": "DGP ≤ 0.45"
          },
          {
            "level": "Medium",
            "threshold": "DGP ≤ 0.40"
          },
          {
            "level": "High",
            "threshold": "DGP ≤ 0.35"
          }
        ]
      },
      "simulation_workflow": {
        "title": "Annual Glare Analysis",
        "hourly_image_generation": "The analysis requires a full 180° fisheye luminance image of the occupant's field of view for every occupied hour of the year. This involves a scripted workflow that repeatedly calls 'rpict' after updating the sky for each hour with 'gensky'.",
        "evalglare_tool": "The 'evalglare' utility is a dedicated tool that takes a fisheye HDR image as input, automatically identifies glare sources, and calculates the DGP value.",
        "automation_script": "A robust script is essential. It must loop through all occupied hours, and for each hour: generate the sky ('gensky'), render the view ('rpict'), calculate glare ('evalglare'), and then parse and log the resulting DGP value."
      },
      "verification": {
        "title": "Post-Processing and Compliance Verification",
        "compiling_results": "The script produces a time-series list of DGP values for all occupied hours.",
        "calculating_exceedance": "This list is analyzed to count the number of hours where the DGP value is greater than the target threshold for the desired performance level.",
        "final_check": "The final percentage of time that glare is excessive is calculated. If this percentage is less than or equal to 5%, the design is compliant."
      }
    }
  },
  {
    "topic": "Core Daylighting Metrics: sDA and ASE",
    "content": {
      "spatial_daylight_autonomy_sDA": {
        "title": "Defining Daylight Sufficiency: Spatial Daylight Autonomy (sDA)",
        "definition": "Spatial Daylight Autonomy (sDA) is an annual, climate-based metric that describes the percentage of a space's regularly occupied floor area that receives a sufficient amount of ambient daylight. It provides a dynamic assessment of performance by using a full year of hourly weather data.",
        "standard_format": "sDA₃₀₀,₅₀%",
        "components": {
          "illuminance_threshold": "300 lux is the target illuminance level on the horizontal work plane, considered sufficient for most common visual tasks.",
          "temporal_threshold": "An individual point is considered 'daylit autonomous' if it meets or exceeds 300 lux for at least 50% of the scheduled occupied hours (typically 8 am to 6 pm daily).",
          "spatial_component": "The final sDA value is the percentage of total analysis points that successfully meet the 50% temporal threshold."
        },
        "precursor_metric": {
          "name": "Daylight Autonomy (DA)",
          "description": "Before sDA can be determined, Daylight Autonomy (DA) must be calculated for each individual sensor point. DA is the percentage of occupied hours that a single point is at or above the specified illuminance threshold. sDA is a spatial summary of these individual DA results."
        }
      },
      "annual_sunlight_exposure_ASE": {
        "title": "Quantifying Sunlight Excess: Annual Sunlight Exposure (ASE)",
        "definition": "Annual Sunlight Exposure (ASE) is a metric designed to identify areas within a space that are prone to excessive direct sunlight, which can lead to visual discomfort (glare) and undesirable solar heat gain.",
        "standard_format": "ASE₁₀₀₀,₂₅₀ₕ",
        "components": {
          "illuminance_threshold": "1000 lux from direct sunlight only. The calculation considers only the illuminance contribution from the solar disc, ignoring diffuse light from the sky or inter-reflected light.",
          "temporal_threshold": "250 hours per year is the maximum number of occupied hours that any point should be exposed to more than 1000 lux of direct sunlight.",
          "spatial_component": "The final ASE value is the percentage of analysis points on the grid that exceed this 250-hour temporal limit."
        },
        "methodological_nuance": "The ASE calculation must be performed assuming any dynamic shading systems (like blinds) are fully open for the entire year. This represents the 'worst-case' potential for direct sun exposure inherent in the building's passive design. This approach forces designers to first address potential glare through robust passive strategies rather than relying solely on active shading."
      }
    }
  },
  {
    "topic": "The IES LM-83 Standard Evolution",
    "content": {
      "overview": "The methodology for calculating sDA and ASE is codified in the IES LM-83 standard. The standard provides a framework for these dynamic, climate-based annual simulations.",
      "evolution": "The standard has undergone significant revision, evolving from the original IES LM-83-12 to the more refined and prescriptive ANSI/IES LM-83-23. This maturation was necessary for its widespread adoption in building codes and green building rating systems like LEED.",
      "key_changes": [
        {
          "change": "Standardized Radiance Parameters",
          "description": "The 2023 version recommends specific Radiance simulation parameters to ensure consistency and comparability between projects and software tools. For sDA, it is now recommended to use 6 ambient bounces (-ab 6) and an ambient division parameter of 1000 (-ad 1000)."
        },
        {
          "change": "ASE Threshold Adjustment",
          "description": "A significant change is the adjustment of the acceptable ASE threshold. While earlier versions cautioned against ASE values exceeding 10%, the newer standard and updated LEED criteria now consider an ASE of up to 20% acceptable in some circumstances, providing designers with greater flexibility."
        }
      ]
    }
  },
  {
    "topic": "The Radiance 3-Phase Simulation Method",
    "content": {
      "paradigm": "The 3-Phase Method is a highly efficient matrix-based approach that decouples the static elements of a simulation (building geometry) from the dynamic elements (hourly sky conditions). This avoids the computationally prohibitive task of running a full simulation for every hour by pre-calculating light transfer relationships and storing them in matrices.",
      "method_breakdown": {
        "title": "The Three Matrices",
        "matrices": [
          {
            "name": "View Matrix (VMX)",
            "description": "Describes the flux transfer from the interior face of the fenestration to the analysis points inside the space. It is calculated using the 'rcontrib' command in a reverse ray-tracing process from the sensors back to the windows."
          },
          {
            "name": "Transmission Matrix (TMX)",
            "description": "Describes the flux transfer through the fenestration itself. This is represented by a Bidirectional Scattering Distribution Function (BSDF) file, which characterizes the complex optical behavior of the glazing and any shading."
          },
          {
            "name": "Daylight Matrix (DMX)",
            "description": "Describes the flux transfer from the sky dome and external obstructions to the exterior face of the fenestration. It is also calculated with 'rcontrib' but traces rays outwards from the windows to the sky."
          }
        ]
      },
      "sky_matrix_SMX": {
        "title": "The Sky Matrix (SMX)",
        "generation": "The Sky Matrix contains the luminance values for every sky patch for every hour of the year. It is generated from a standard EPW weather file using the 'gendaymtx' utility.",
        "versions": [
          {
            "name": "Full Sky Matrix",
            "usage": "Contains luminance from both the diffuse sky and direct sun. It is used for the final sDA illuminance calculation."
          },
          {
            "name": "Direct-Only Sky Matrix",
            "usage": "Contains only the contribution from the direct sun. It is essential for the ASE calculation and for generating the blind operation schedule."
          }
        ]
      },
      "synthesis": {
        "title": "Synthesizing the Data",
        "command": "The 'dctimestep' program performs the final, rapid matrix multiplication to calculate hourly illuminance values for the entire year.",
        "equation": "Illuminance_annual = VMX × TMX × DMX × SMX",
        "output": "The output is a large data file where each row corresponds to a sensor point and each column corresponds to an hour of the year, with the values being the calculated illuminance levels."
      }
    }
  },
  {
    "topic": "Advanced Simulation: The 5-Phase Method",
    "content": {
      "limitations_of_3_phase": "The primary inaccuracy of the 3-Phase Method is in its handling of direct sun. The sun's intense energy is averaged or 'smeared' across a large sky patch, which can lead to a loss of directional precision and a softening of shadows. This can misrepresent the performance of Complex Fenestration Systems (CFS) like light shelves or specular louvers.",
      "introduction_to_5_phase": "The 5-Phase Method is a refinement that improves upon the 3-Phase Method by explicitly separating the direct solar component from the diffuse sky and inter-reflected components, allowing it to be calculated with much higher precision.",
      "conceptual_process": [
        "1. Calculate total illuminance using the standard 3-Phase method.",
        "2. Calculate the inaccurate direct sun component using a 3-Phase calculation with a direct-sun-only sky matrix.",
        "3. Subtract the inaccurate direct sun (Step 2) from the total illuminance (Step 1).",
        "4. Calculate an accurate direct sun component using a separate, high-precision method.",
        "5. Add the accurate direct sun (Step 4) back to the result from Step 3 for the final, corrected illuminance value."
      ],
      "when_to_use": {
        "3-Phase_Method": "Sufficient and recommended for early-stage design and for projects with conventional, non-redirecting fenestration systems.",
        "5-Phase_Method": "Justified and preferred for the final, high-accuracy analysis of projects featuring complex fenestration systems like light shelves, prismatic panels, or specular blinds."
      }
    }
  },
  {
    "topic": "Dynamic Shading in sDA Calculations",
    "content": {
      "concept": "A significant innovation of the IES LM-83 standard is its requirement to simulate the dynamic operation of window shades or blinds. This incorporates a simplified model of occupant behavior, where occupants act to mitigate discomfort from direct sunlight, making sDA a far more realistic predictor of real-world performance.",
      "blind_operation_logic": {
        "title": "The Logic of Blind Operation",
        "trigger": "For any given hour, if more than a specified percentage of the analysis area (typically 2%) receives more than 1000 lux of direct sunlight, the blinds associated with the offending window(s) are considered to be in the 'closed' state for that hour.",
        "proxy_for_behavior": "This clear, deterministic algorithm provides a simple, computable proxy for an occupant's response to unacceptable glare conditions, representing a pragmatic and necessary simplification of complex human behavior."
      },
      "schedule_generation_workflow": {
        "title": "Generating the Blind Schedule",
        "steps": [
          "1. Calculate the annual direct-only illuminance at each sensor point, assuming all blinds are open.",
          "2. For each occupied hour, count the number of sensor points where the direct illuminance exceeds 1000 lux.",
          "3. If the percentage of points exceeding the threshold is greater than the trigger value (e.g., 2%), record that hour as 'blinds closed' in a schedule file; otherwise, record it as 'blinds open'. This is done on a per-window-group basis."
        ]
      },
      "applying_the_schedule": {
        "title": "Applying the Schedule to Simulations",
        "requirement": "This step requires the results from two separate, full annual simulations: one run with a BSDF file for the 'blinds open' state, and a second run with a BSDF for the 'blinds closed' state.",
        "final_matrix_assembly": "A final post-processing script creates a definitive 'operated' annual illuminance matrix. It iterates through each hour, consults the blind schedule, and copies the appropriate illuminance value from either the 'blinds open' or 'blinds closed' simulation results into the final matrix."
      }
    }
  },
  {
    "topic": "Post-Processing and Design Interpretation",
    "content": {
      "calculating_sDA": {
        "title": "Calculating Spatial Daylight Autonomy (sDA)",
        "step_1": "Calculate Per-Point Daylight Autonomy (DA): Using the final 'operated' illuminance matrix, for each sensor point, count the number of occupied hours where illuminance is ≥ 300 lux. Divide this by the total number of occupied hours to get the DA percentage for that point.",
        "step_2": "Aggregate for sDA: Count the number of sensor points with a DA value ≥ 50%. Divide this count by the total number of sensor points to get the final sDA₃₀₀,₅₀% for the space."
      },
      "calculating_ASE": {
        "title": "Calculating Annual Sunlight Exposure (ASE)",
        "step_1": "Tally Per-Point Hours: Using the direct-sun-only, blinds-open illuminance matrix, for each sensor point, count the number of occupied hours where the direct-only illuminance is > 1000 lux.",
        "step_2": "Aggregate for ASE: Count the number of sensor points where the hour count is > 250. Divide this count by the total number of sensor points to get the final ASE₁₀₀₀,₂₅₀ₕ percentage for the space."
      },
      "design_interpretation": {
        "title": "Interpreting Results for Design",
        "case_study_takeaways": [
          "The Power of Shading: Passive solar control strategies, like fixed shading and light shelves, are the most critical first step and provide the most dramatic improvements in performance, simultaneously reducing ASE and increasing sDA.",
          "The Benefit of Granular Control: Dividing large window areas into smaller, independently controlled groups (e.g., separating a view window from a clerestory) allows for more nuanced blind control and can significantly improve sDA.",
          "The Sensitivity of the Metrics: The final sDA and ASE values are highly sensitive to the inputs and assumptions of the simulation (like the analysis period or script version), reinforcing the need to strictly adhere to standardized methodologies like IES LM-83."
        ]
      },
      "strategic_recommendations": [
        "Prioritize Passive Strategies First: Use the ASE metric as a design tool in the earliest project stages to mitigate direct sun exposure through orientation, massing, and fixed shading.",
        "Employ Granular Control: Design fenestration that can be controlled in smaller, independent zones to optimize daylight penetration while managing glare.",
        "Select the Appropriate Simulation Method: Use the efficient 3-Phase Method for rapid iteration and simple designs, and reserve the more accurate 5-Phase Method for final validation of projects with complex fenestration.",
        "Understand Your Tools: Do not treat simulation software as an infallible 'black box'. Understand the default settings and assumptions to ensure they are appropriate for the design and compliant with the latest standards."
      ]
    }
  }
]