Every result starts
with an assumption.

The courtyard has a flat rectangular floor, four opaque vertical walls of equal height, and an open top. Incoming sunlight is represented by parallel rays at a specified elevation and azimuth.

Included

• Direct geometric shading by the four courtyard walls.
• Changes in aspect ratio at a constant 100 m² floor area.
• Uniform wall height and a single chosen sun position per calculation.

Outside the model

Weather, diffuse sky radiation, reflections, wall thickness, vegetation, neighboring buildings, surface materials, and thermal response are excluded. Sun position is supplied as an angle, rather than derived from latitude, date, or time.

A sunlit fraction is not an irradiance, temperature, comfort, or energy prediction. The results have numerical checks; they are not field measurements or empirical validation.

Let W and L be the courtyard’s floor width and length, H the wall height, α the solar elevation, and β the azimuth measured clockwise from the upward length axis in plan view.

Trace a ray from the floor toward the sun. Over the vertical distance H, the ray moves horizontally by d. A floor point receives direct sunlight if that ray passes through the open top without intersecting a wall.

The sunlit region is the overlap between the floor rectangle and its displaced opening. If either overlap dimension reaches zero, the whole floor is shaded.

Fixed area, variable proportions

For floor area A and aspect ratio r = L/W, width is √(A/r) and length is √(A × r). The published sweep uses A = 100 m².

The interactive model also accepts intermediate values and a wider input range. A downloaded single calculation may therefore fall outside the published 315-case sweep.

Geometric checks

The released checker executes 1,585 assertions: 6 reference and limiting checks, 1,575 checks across the parameter sweep, and 4 ray-grid error bounds. The sweep checks cover bounded fractions, symmetry under a 180° change in sun direction, wall-height and solar-elevation monotonicity, and geometric scale invariance.

Independent ray sampling

A separate calculation samples floor points and tests whether rays toward the sun clear the walls. Six configurations are compared at four sampling resolutions: one benchmark from the published grid and five configurations outside it.

The largest discrepancy at 320 × 320 points is about 0.188 percentage points. This measures discretization differences in the tested cases; it is not an uncertainty estimate for a real courtyard.

Browser and Python agreement

The JavaScript module used by the browser and the Python model were compared across all 315 published cases. Their largest absolute difference in sunlit fraction was 2.78 × 10⁻¹⁶, consistent with floating-point arithmetic.

The complete verification report records the six ray-sampling inputs, all 24 comparisons, exact dataset regeneration, implementation agreement, software versions, and source hashes. The reproduction script reruns these checks locally.

Download the Python source and use Python 3.10 or later. No additional packages are required.

Run the verification checks

python3 courtyard-study.v1.py --check

Generate the complete dataset

python3 courtyard-study.v1.py > courtyard-results.csv

Compare the output with the published CSV. The release manifest records parameters, numerical checks, byte sizes, and SHA-256 hashes for the distributed files.

The browser’s JavaScript model implements the same analytical calculation. The interactive controls call this model locally.

Reproduce the complete verification

Use Python 3.10 or later and Node.js 18 or later. No extra packages or network access are required. Save these six files in the same folder:

• courtyard-reproduce.v1.py · verification driver
• courtyard-study.v1.py · Python model
• courtyard-model.v1.js · browser model
• courtyard-results.v1.csv · published data
• courtyard-manifest.v1.json · release hashes
• LICENSE.txt · reuse terms

python3 -B courtyard-reproduce.v1.py --browser-model courtyard-model.v1.js

The script prints a JSON report after checking file integrity, regenerating the CSV, running the released assertions, recording the ray-sampling comparisons, and comparing Python with the JavaScript module in Node.js. A changed input file or failed comparison returns an error. Runtime versions can differ from the published report; the numerical acceptance tolerance is stated in that report.

Report a reproducibility issue

Include the model version, command or input values, expected result, and observed result in a message to osama.khaled@ablaqstudios.com.

The study applies established solar-shading geometry. It does not claim a new shading theory.

EnergyPlus Engineering Reference: Shading Module describes the geometric treatment of direct solar shading in building simulation. It is a methodological reference. EnergyPlus was not used as the calculation engine or as an independent validator of this release.

Publication record

Version 1.0 was published by ABLAQ Studios on 12 October 2026 as a computational study with numerical verification. It has not undergone external peer review or validation against field measurements.

Documentation update, 12 October 2026: the verification description now identifies the exact check inventory and distinguishes one benchmark from five off-grid cases. A reproduction script and detailed verification report were added. The original model, dataset, and release manifest are unchanged.

Download the study and verification files.

Programme leadership and decision-making

The scientific programme is led by Osama Khaled Ahmed Abdel-Qader. His responsibilities cover research direction, commissioning, the standards for published evidence, and accountability for the research record. The study contribution statement documents the scope of that leadership.

Scope and interpretation

The published investigation isolates direct geometric solar exposure. Its analytical assumptions, parameter sweep, and numerical comparisons are stated above. Claims about temperature, comfort, or annual energy performance would require evidence beyond this release.

AI-assisted technical work

AI tools supported literature discovery, computational implementation, execution of numerical checks, and preparation of technical documentation. The released model, dataset, and recorded checks provide the evidence for the findings. ABLAQ Studios is the institutional author and publisher.

The separate ray-sampling calculation checks the analytical solution using another numerical method. It is not an external replication, peer review, or empirical validation.

Corrections and the research record

Scientific questions and proposed corrections go to the programme lead at osama.khaled@ablaqstudios.com. Include the version, inputs, expected outcome, and observed result. The version manifest identifies the released files and their hashes so that a report can be tied to the exact study record.