PERF: vectorize PeriodIndex.from_fields

Add period_ordinals_from_fields Cython function that converts arrays of
year/month/day/hour/minute/second fields to period ordinals in a single
C-level loop, replacing the Python-space list-append loop in
_range_from_fields, and vectorize the quarter-to-calendar-month
conversion with numpy ops.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: jbrockmendel

doc/source/whatsnew/v3.1.0.rst

@@ -206,6 +206,7 @@ Performance improvements
 - Performance improvement in :meth:`Index.join` and :meth:`Index.union` for :class:`RangeIndex` by avoiding unnecessary memory allocation in the libjoin fastpath (:issue:`54646`)
 - Performance improvement in :meth:`IntervalIndex.get_indexer` for monotonic non-overlapping indexes, which now uses binary search instead of the interval tree (:issue:`47614`)
 - Performance improvement in :meth:`NDFrame.__finalize__`, :meth:`Series.to_numpy`, :attr:`DataFrame.dtypes`, and :meth:`DataFrame.__getitem__` (:issue:`57431`)
+- Performance improvement in :meth:`PeriodIndex.from_fields` (:issue:`65921`)
 - Performance improvement in :meth:`Timedelta.total_seconds` (:issue:`65388`)
 - Performance improvement in :meth:`arrays.SparseArray.isna` by avoiding a dense-then-resparsify round-trip (:issue:`41023`)
 - Performance improvement in datetime/timedelta unit conversion (e.g. ``datetime64[s]`` to ``datetime64[ns]``) (:issue:`35025`)

pandas/_libs/tslibs/period.pyi

@@ -31,6 +31,15 @@ def get_period_field_arr(
     arr: npt.NDArray[np.int64],  # const int64_t[:]
     freq: int,
 ) -> npt.NDArray[np.int64]: ...
+def period_ordinals_from_fields(
+    years: npt.NDArray[np.int64],
+    months: npt.NDArray[np.int64],
+    days: npt.NDArray[np.int64],
+    hours: npt.NDArray[np.int64],
+    minutes: npt.NDArray[np.int64],
+    seconds: npt.NDArray[np.int64],
+    freq: int,
+) -> npt.NDArray[np.int64]: ...
 def from_calendar_ordinals(
     values: npt.NDArray[np.int64],  # const int64_t[:]
     dtype: PeriodDtypeBase,

pandas/_libs/tslibs/period.pyx

@@ -27,6 +27,7 @@ from cpython.datetime cimport (
     datetime,
     import_datetime,
 )
+from libc.stdint cimport INT32_MAX
 from libc.stdlib cimport (
     free,
     malloc,
@@ -1567,6 +1568,61 @@ cdef accessor _get_accessor_func(str field):
     return NULL
 
 
+@cython.wraparound(False)
+@cython.boundscheck(False)
+def period_ordinals_from_fields(
+    const int64_t[:] years,
+    const int64_t[:] months,
+    const int64_t[:] days,
+    const int64_t[:] hours,
+    const int64_t[:] minutes,
+    const int64_t[:] seconds,
+    int freq,
+):
+    """
+    Vectorized version of period_ordinal: convert arrays of date/time fields
+    to an array of period ordinals for the given frequency.
+
+    Parameters
+    ----------
+    years, months, days, hours, minutes, seconds : int64 arrays
+    freq : int
+
+    Returns
+    -------
+    ndarray[int64]
+    """
+    cdef:
+        Py_ssize_t i, n = len(years)
+        int64_t[::1] result = np.empty(n, dtype="i8")
+        npy_datetimestruct dts
+
+    memset(&dts, 0, sizeof(npy_datetimestruct))
+
+    for i in range(n):
+        # month/day/hour/min/sec land in int32 npy_datetimestruct fields,
+        #  so values outside int32 range would silently wrap; period_ordinal
+        #  raises OverflowError for these (C int args), so match that.
+        if (
+            not (INT32_MIN <= years[i] <= INT32_MAX)
+            or not (INT32_MIN <= months[i] <= INT32_MAX)
+            or not (INT32_MIN <= days[i] <= INT32_MAX)
+            or not (INT32_MIN <= hours[i] <= INT32_MAX)
+            or not (INT32_MIN <= minutes[i] <= INT32_MAX)
+            or not (INT32_MIN <= seconds[i] <= INT32_MAX)
+        ):
+            raise OverflowError("value too large to convert to int")
+        dts.year = years[i]
+        dts.month = months[i]
+        dts.day = days[i]
+        dts.hour = hours[i]
+        dts.min = minutes[i]
+        dts.sec = seconds[i]
+        result[i] = get_period_ordinal(&dts, freq)
+
+    return result.base
+
+
 @cython.wraparound(False)
 @cython.boundscheck(False)
 def from_calendar_ordinals(const int64_t[:] values, PeriodDtypeBase dtype):

pandas/core/arrays/period.py

@@ -35,6 +35,7 @@
     period as libperiod,
     to_offset,
 )
+from pandas._libs.tslibs.ccalendar import MONTH_NUMBERS
 from pandas._libs.tslibs.dtypes import (
     FreqGroup,
     PeriodDtypeBase,
@@ -1568,8 +1569,6 @@ def _range_from_fields(
     if day is None:
         day = 1
 
-    ordinals = []
-
     if quarter is not None:
         if freq is None:
             freq = to_offset("Q", is_period=True)
@@ -1582,20 +1581,38 @@ def _range_from_fields(
 
         freqstr = freq.freqstr
         year, quarter = _make_field_arrays(year, quarter)
-        for y, q in zip(year, quarter, strict=True):
-            calendar_year, calendar_month = parsing.quarter_to_myear(y, q, freqstr)
-            val = libperiod.period_ordinal(
-                calendar_year, calendar_month, 1, 1, 1, 1, 0, 0, base
-            )
-            ordinals.append(val)
+        year = np.asarray(year, dtype=np.int64)
+        quarter = np.asarray(quarter, dtype=np.int64)
+
+        if (quarter < 1).any() or (quarter > 4).any():
+            raise ValueError("Quarter must be 1 <= q <= 4")
+
+        # Vectorized quarter_to_myear
+        mnum = MONTH_NUMBERS[parsing.get_rule_month(freqstr)] + 1
+        months = (mnum + (quarter - 1) * 3) % 12 + 1
+        years = np.where(months > mnum, year - 1, year)
+
+        length = len(years)
+        ones = np.ones(length, dtype=np.int64)
+        zeros = np.zeros(length, dtype=np.int64)
+        ordinals = libperiod.period_ordinals_from_fields(
+            years, months, ones, zeros, zeros, zeros, base
+        )
     else:
         freq = to_offset(freq, is_period=True)
         base = libperiod.freq_to_dtype_code(freq)
         arrays = _make_field_arrays(year, month, day, hour, minute, second)
-        for y, mth, d, h, mn, s in zip(*arrays, strict=True):
-            ordinals.append(libperiod.period_ordinal(y, mth, d, h, mn, s, 0, 0, base))
+        ordinals = libperiod.period_ordinals_from_fields(
+            arrays[0].astype(np.int64, copy=False),
+            arrays[1].astype(np.int64, copy=False),
+            arrays[2].astype(np.int64, copy=False),
+            arrays[3].astype(np.int64, copy=False),
+            arrays[4].astype(np.int64, copy=False),
+            arrays[5].astype(np.int64, copy=False),
+            base,
+        )
 
-    return np.array(ordinals, dtype=np.int64), freq
+    return ordinals, freq
 
 
 def _make_field_arrays(*fields) -> list[np.ndarray]:

pandas/tests/indexes/period/test_constructors.py

@@ -241,6 +241,49 @@ def test_constructor_invalid_quarters(self):
                 year=range(2000, 2004), quarter=list(range(4)), freq="Q-DEC"
             )
 
+    def test_constructor_field_arrays_quarter_no_freq(self):
+        # Quarter with no explicit freq infers Q-DEC
+        years = np.array([2020, 2020, 2020, 2020], dtype=np.int64)
+        quarters = np.array([1, 2, 3, 4], dtype=np.int64)
+        result = PeriodIndex.from_fields(year=years, quarter=quarters)
+        expected = PeriodIndex(
+            [Period(year=2020, quarter=q, freq="Q-DEC") for q in range(1, 5)]
+        )
+        tm.assert_index_equal(result, expected)
+
+    def test_constructor_field_arrays_hourly(self):
+        # Test non-quarter path with all 6 fields
+        result = PeriodIndex.from_fields(
+            year=[2020, 2020],
+            month=[1, 6],
+            day=[15, 20],
+            hour=[10, 22],
+            minute=[30, 45],
+            second=[5, 59],
+            freq="s",
+        )
+        expected = PeriodIndex(
+            [
+                Period("2020-01-15 10:30:05", freq="s"),
+                Period("2020-06-20 22:45:59", freq="s"),
+            ]
+        )
+        tm.assert_index_equal(result, expected)
+
+    def test_constructor_field_arrays_empty(self):
+        # Empty arrays should produce empty PeriodIndex
+        result = PeriodIndex.from_fields(year=[], month=[], freq="M")
+        expected = PeriodIndex([], dtype="period[M]")
+        tm.assert_index_equal(result, expected)
+
+    @pytest.mark.parametrize("field", ["year", "month"])
+    def test_constructor_field_arrays_outside_int32(self, field):
+        # Fields outside int32 range must raise instead of wrapping silently
+        fields = {"year": [2000, 2000], "month": [3, 3]}
+        fields[field] = [fields[field][0], 2**32 + 3]
+        with pytest.raises(OverflowError, match="value too large"):
+            PeriodIndex.from_fields(**fields, freq="M")
+
     def test_period_range_fractional_period(self):
         msg = "periods must be an integer, got 10.5"
         with pytest.raises(TypeError, match=msg):