# eunoia.euler

Python · 0.6.0

[Source](<https://github.com/jolars/eunoia-py/blob/af16491d64a6d1f3b87b8645bd9697593daa0f02/python/eunoia/_fit.py>)

<a id="overload-83195a567a5ec9af514cbc8d375f43660b6f84fc8428cf5ddabc422d29234290"></a>

```python
euler(
    values: EulerInput,
    *,
    input: typing.Literal["exclusive", "inclusive"] = ...,
    names: Sequence[str] | None = ...,
    ids: str | Sequence[object] | None = ...,
    shape: typing.Literal["circle"] = ...,
    seed: int | None = ...,
    complement: float | None = ...,
    loss: Loss | None = ...,
    optimizer: Optimizer | None = ...,
    tolerance: float | None = ...,
    n_restarts: int | None = ...,
    max_iterations: int | None = ...,
    n_threads: int | None = ...
) -> eunoia.EulerFit[eunoia.Circle]
```

<a id="overload-e99a27d71a98723ade3469eff42307d8f7c15ba200b9fdede191f02d57936225"></a>

```python
euler(
    values: EulerInput,
    *,
    input: typing.Literal["exclusive", "inclusive"] = ...,
    names: Sequence[str] | None = ...,
    ids: str | Sequence[object] | None = ...,
    shape: typing.Literal["ellipse"],
    seed: int | None = ...,
    complement: float | None = ...,
    loss: Loss | None = ...,
    optimizer: Optimizer | None = ...,
    tolerance: float | None = ...,
    n_restarts: int | None = ...,
    max_iterations: int | None = ...,
    n_threads: int | None = ...
) -> eunoia.EulerFit[eunoia.Ellipse]
```

<a id="overload-69b2fa4912e8c32221fa6301757f22096b743c94e45a0206f27bded4fb937ade"></a>

```python
euler(
    values: EulerInput,
    *,
    input: typing.Literal["exclusive", "inclusive"] = ...,
    names: Sequence[str] | None = ...,
    ids: str | Sequence[object] | None = ...,
    shape: typing.Literal["square"],
    seed: int | None = ...,
    complement: float | None = ...,
    loss: Loss | None = ...,
    optimizer: Optimizer | None = ...,
    tolerance: float | None = ...,
    n_restarts: int | None = ...,
    max_iterations: int | None = ...,
    n_threads: int | None = ...
) -> eunoia.EulerFit[eunoia.Square]
```

<a id="overload-880e6e889884725dbaad1ac500040c20ddb71abf91c7bccea1abea5169c9598a"></a>

```python
euler(
    values: EulerInput,
    *,
    input: typing.Literal["exclusive", "inclusive"] = ...,
    names: Sequence[str] | None = ...,
    ids: str | Sequence[object] | None = ...,
    shape: typing.Literal["rectangle"],
    seed: int | None = ...,
    complement: float | None = ...,
    loss: Loss | None = ...,
    optimizer: Optimizer | None = ...,
    tolerance: float | None = ...,
    n_restarts: int | None = ...,
    max_iterations: int | None = ...,
    n_threads: int | None = ...
) -> eunoia.EulerFit[eunoia.Rectangle]
```

<a id="overload-023afbe3c789d929509c3eb24706d118c1ef292b81dbb1a765a885cf629a55a4"></a>

```python
euler(
    values: EulerInput,
    *,
    input: typing.Literal["exclusive", "inclusive"] = ...,
    names: Sequence[str] | None = ...,
    ids: str | Sequence[object] | None = ...,
    shape: typing.Literal["rotated_rectangle"],
    seed: int | None = ...,
    complement: float | None = ...,
    loss: Loss | None = ...,
    optimizer: Optimizer | None = ...,
    tolerance: float | None = ...,
    n_restarts: int | None = ...,
    max_iterations: int | None = ...,
    n_threads: int | None = ...
) -> eunoia.EulerFit[eunoia.RotatedRectangle]
```

Fit an area-proportional Euler diagram.

<a id="parameters"></a>

## Parameters

`values:`

One of three forms:

- a mapping from set-combination labels (e.g. `"A"`, `"A&B"`) to their areas;
- a mapping from set names to membership collections (`{"A": ["x", "y"], "B": ["y", "z"]}`);
- a DataFrame (pandas, polars, or anything narwhals supports) treated as a membership matrix: each column is a set, each row an observation, and a truthy cell denotes membership. Columns must be boolean or `0/1` numeric.
- a numpy boolean array used as a membership matrix (the matrix idiom from eulerr): a 2-D `(n_observations, n_sets)` array, or a 1-D array read as a single set. Values must be boolean or `0/1` numeric; `NaN` cells count as non-members. Set names come from `names` or are generated (`"A"`, `"B"`, …).

For the membership-list, DataFrame, and array forms, each element/row is counted into the canonical region of the sets it belongs to, yielding exclusive per-region counts (so `input` must stay `"exclusive"`).

`input:`

`"exclusive"` (default): values are per-region areas, with no overlap from other sets included. `"inclusive"`: values are total set sizes that include overlaps; the eunoia core converts internally.

`names:`

Set names for numpy-array input, one per column (or a single name for a 1-D array). Defaults to `"A"`, `"B"`, …. Only valid for array input; other forms carry their own names and passing `names` raises.

`ids:`

Per-observation member identifiers, so the fit retains *who* is in each region (surfaced as [`members`](<368c6eef5f44d1af6db73a3b8b4a2c7058500ce15acc586ff7b67311c0627c97#members>) and drawable with `plot(members=True)`). Only valid for array and DataFrame input: pass a sequence with one entry per row (array or DataFrame), or, for a DataFrame, the name of a column to read the identifiers from and exclude from the sets. Membership-list input carries its members intrinsically (no `ids` needed); passing `ids` with any other form raises.

`shape:`

`"circle"` (default), `"ellipse"`, `"square"`, `"rectangle"`, or `"rotated_rectangle"`.

`seed:`

Optional seed for the optimizer's RNG (for reproducibility).

`complement:`

Area outside every named set (the universe or "complement"). When given, the core jointly fits a container box and the result carries a `container`. Requires every set to overlap into one cluster.

`loss:`

The objective the optimizer minimizes. `None` (default) uses the core default, `"sum_squared"` (normalized sum of squared region residuals). Other options trade off how error is distributed across regions, e.g. `"sum_absolute"`, `"stress"` (venneuler-style), `"diag_error"` (eulerAPE worst-region), the region-error variants, and the max-error variants. See `Loss`.

`optimizer:`

The final-stage optimizer the core uses. `None` (default) keeps the core default, `"cma_es_trf"` (CMA-ES global escape with a bounded trust-region-reflective polish). Other options trade robustness for speed: `"levenberg_marquardt"`, `"lbfgs"`, `"nelder_mead"`, `"cma_es"`, `"cma_es_lm"`, `"trf"`, `"mads"` (a derivative-free mesh-adaptive direct search). See `Optimizer`.

`tolerance:`

Cost-change convergence tolerance for the final-stage optimizer. `None` keeps the core default (`1e-3`); smaller values fit more tightly at the cost of more iterations.

`n_restarts:`

Number of full-pipeline restarts (fresh initialization + optimization), keeping the lowest-loss result. `None` keeps the core default (`10`). Higher values better approach the global optimum but cost proportionally more; `1` disables restarts.

`max_iterations:`

Maximum optimizer iterations per fit. `None` keeps the core default (`200`).

`n_threads:`

Number of threads used to run the `n_restarts` restarts in parallel. `None` (default) uses all available logical cores; a positive integer caps the thread pool, and `1` runs serially. This does not affect the result of a seeded fit (the lowest-loss restart is selected regardless of completion order), only how fast it is computed. The default pool also honors the `RAYON_NUM_THREADS` environment variable.

<a id="returns"></a>

## Returns

`EulerFit`

A fit result with shapes, original/fitted values, residuals, region error, diag\_error, stress, and loss.