Metadata-Version: 2.2
Name: cea-external-tools
Version: 0.2.2
Summary: External tools for City Energy Analyst, mainly containing C++ components e.g. DAYSIM and CRAX
Author-Email: Reynold Mok <reynold.mok@arch.ethz.ch>
License: MIT License
         
         Copyright (c) 2025 Architecture and Building Systems, ETH Zurich
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
         
         
         ===============================================================================
         THIRD-PARTY LICENSES
         ===============================================================================
         
         This software includes binaries compiled from third-party open source projects.
         See the vendored/licenses/ directory for the full license texts of these
         dependencies:
         
         - Daysim/Radiance: vendored/licenses/DAYSIM-LICENSE.txt
         
Project-URL: Homepage, https://cityenergyanalyst.com
Project-URL: Bug Reports, https://github.com/architecture-building-systems/CityEnergyAnalyst/issues
Project-URL: Source, https://github.com/architecture-building-systems/CityEnergyAnalyst
Requires-Python: <3.13,>=3.8
Description-Content-Type: text/markdown

# CEA External Tools

**A standalone Python package containing compiled C++ tools for the City Energy Analyst (CEA).**

This package provides pre-compiled binary executables for radiation calculations and urban energy modeling, including DAYSIM (daylighting simulation) and CRAX (City Radiation Accelerator). 

By separating these computationally intensive C++ components into their own package, we enable faster CEA installations and reduce build complexity.

## Installation

```bash
pip install cea-external-tools
```

## Usage

```python
import cea_external_tools

# Get path to binary tools
bin_path = cea_external_tools.get_bin_path()
print(f"External tools located at: {bin_path}")
```

## Package Contents

This package includes compiled binaries for:
- **DAYSIM** - Advanced daylighting simulation tools
- **CRAX** - Fast urban radiation calculation engine

---

## Development & Build Configuration

This directory contains the CMake configuration for building external tools required by the City Energy Analyst (CEA).

## Structure

The build system has been modularized into separate configuration files:

- **`CMakeLists.txt`** - Main build configuration file
- **`DaysimConfig.cmake`** - DAYSIM-specific configuration and build logic  
- **`CraxConfig.cmake`** - CRAX-specific configuration and build logic

## Components

### DAYSIM
Daylighting simulation tool that provides various radiation calculation utilities.

**Executables built:**
- `ds_illum` - Illuminance calculation
- `epw2wea` - Weather file conversion  
- `gen_dc` - Daylight coefficient generation
- `oconv` - Octree conversion
- `radfiles2daysim` - Radiance file conversion
- `rtrace_dc` - Ray tracing for daylight coefficients

### CRAX
City Radiation Accelerator for fast urban radiation simulations.

**Executables built:**
- `radiation` - Main radiation calculation engine
- `mesh-generation` - 3D mesh generation utility

## Build Options

You can control which components to build using CMake options:

```bash
# Build both components (default)
cmake -DBUILD_DAYSIM=ON -DBUILD_CRAX=ON ..

# Build only DAYSIM
cmake -DBUILD_DAYSIM=ON -DBUILD_CRAX=OFF ..

# Build only CRAX  
cmake -DBUILD_DAYSIM=OFF -DBUILD_CRAX=ON ..
```

## CRAX-specific Options

CRAX has additional configuration options for Python wheel builds:

- `CRAX_USE_DYNAMIC_ARROW` (default: ON) - Enable dynamic Arrow linking to save space in wheels
- `CRAX_USE_AUTOMATED_DEPENDENCIES` (default: ON) - Use automated dependency fetching

## Source Configuration

Both tools support local source directories or automatic fetching from GitHub:

### DAYSIM
- `DAYSIM_SOURCE_DIR` - Path to local DAYSIM source (default: `./daysim`)
- `DAYSIM_GIT_REPOSITORY` - Git repository URL (default: `https://github.com/reyery/Daysim.git`)
- `DAYSIM_GIT_TAG` - Git tag/branch to use

### CRAX
- `CRAX_SOURCE_DIR` - Path to local CRAX source (default: `./crax`)
- `CRAX_GIT_REPOSITORY` - Git repository URL (default: `https://github.com/wanglittlerain/CityRadiation-Accelerator-CRAX-V1.0.git`)
- `CRAX_GIT_TAG` - Git tag/branch to use

## Installation

The built executables are installed to the CEA resources directory:
- CRAX tools: `cea_external_tools/bin`

## Build Targets

The build system includes a custom target `cea_all` that builds all required CEA components:

```bash
# Configure build
cmake -B build -S .

# Build all CEA targets (recommended)
cmake --build build --target cea_all

# Or build all targets
cmake --build build

# Install to CEA resources
cmake --install build
```

## Compiler Warnings

The build system automatically suppresses common warnings for cleaner output:
- GNU/Clang: Suppresses missing prototypes, unused variables, sign comparison, and deprecated declarations
- MSVC: Suppresses warning C4127 to prevent build failures on Windows
