# Source code for brian2.groups.group

    """
    This module defines the `VariableOwner` class, a mix-in class for everything
    that saves state variables, e.g. `Clock` or `NeuronGroup`, the class `Group`
    for objects that in addition to storing state variables also execute code, i.e.
    objects such as `NeuronGroup` or `StateMonitor` but not `Clock`, and finally
    `CodeRunner`, a class to run code in the context of a `Group`.
    """

    import inspect
    import numbers
    import weakref
    from collections import OrderedDict
    from collections.abc import Mapping

    import numpy as np

    from brian2.codegen.codeobject import create_runner_codeobj
    from brian2.core.base import BrianObject, weakproxy_with_fallback
    from brian2.core.functions import Function
    from brian2.core.names import Nameable, find_name
    from brian2.core.namespace import (
        DEFAULT_CONSTANTS,
        DEFAULT_FUNCTIONS,
        DEFAULT_UNITS,
        get_local_namespace,
    )
    from brian2.core.preferences import prefs
    from brian2.core.variables import (
        ArrayVariable,
        AuxiliaryVariable,
        Constant,
        DynamicArrayVariable,
        LinkedVariable,
        Subexpression,
        Variable,
        Variables,
    )
    from brian2.equations.equations import BOOLEAN, FLOAT, INTEGER, Equations
    from brian2.importexport.importexport import ImportExport
    from brian2.units.fundamentalunits import (
        DIMENSIONLESS,
        DimensionMismatchError,
        fail_for_dimension_mismatch,
        get_unit,
    )
    from brian2.utils.logger import get_logger
    from brian2.utils.stringtools import SpellChecker, get_identifiers

    __all__ = ["Group", "VariableOwner", "CodeRunner"]

    logger = get_logger(__name__)

    def _display_value(obj):
        """
        Helper function for warning messages that display the value of objects. This
        functions returns a nicer representation for symbolic constants and
        functions.

        Parameters
        ----------
        obj : object
            The object to display

        Returns
        -------
        value : str
            A string representation of the object
        """
        if isinstance(obj, Function):
            return "<Function>"
        try:
            obj = obj.get_value()
        except AttributeError:
            pass
        try:
            obj = obj.value
        except AttributeError:
            pass

        # We (temporarily) set numpy's print options so that array with more than
        # 10 elements are only shown in an abbreviated way
        old_options = np.get_printoptions()
        np.set_printoptions(threshold=10)
        try:
            str_repr = repr(obj)
        except Exception:
            str_repr = f"<object of type {type(obj)}>"
        finally:
            np.set_printoptions(**old_options)
        return str_repr

    def _conflict_warning(message, resolutions):
        """
        A little helper functions to generate warnings for logging. Specific
        to the `Group._resolve` method and should only be used by it.

        Parameters
        ----------
        message : str
            The first part of the warning message.
        resolutions : list of str
            A list of (namespace, object) tuples.
        """
        if len(resolutions) == 0:
            # nothing to warn about
            return
        elif len(resolutions) == 1:
            second_part = (
                "but the name also refers to a variable in the "
                f"{resolutions[0][0]} "
                f"namespace with value '{_display_value(resolutions[0][1])}'."
            )
        else:
            second_part = (
                "but the name also refers to a variable in the following "
                f"namespaces: {', '.join([r[0] for r in resolutions])}."
            )

        logger.warn(
            f"{message} {second_part}", "Group.resolve.resolution_conflict", once=True
        )

    def get_dtype(equation, dtype=None):
        """
        Helper function to interpret the `dtype` keyword argument in `NeuronGroup`
        etc.

        Parameters
        ----------
        equation : `SingleEquation`
            The equation for which a dtype should be returned
        dtype : `dtype` or dict, optional
            Either the `dtype` to be used as a default dtype for all float variables
            (instead of the `core.default_float_dtype` preference) or a
            dictionary stating the `dtype` for some variables; all other variables
            will use the preference default

        Returns
        -------
        d : `dtype`
            The dtype for the variable defined in `equation`
        """
        # Check explicitly provided dtype for compatibility with the variable type
        if isinstance(dtype, Mapping):
            if equation.varname in dtype:
                BASIC_TYPES = {BOOLEAN: "b", INTEGER: "iu", FLOAT: "f"}
                provided_dtype = np.dtype(dtype[equation.varname])
                if provided_dtype.kind not in BASIC_TYPES[equation.var_type]:
                    raise TypeError(
                        "Error determining dtype for variable "
                        f"{equation.varname}: {provided_dtype.name} is not "
                        f"a correct type for {equation.var_type} variables"
                    )
                else:
                    return dtype[equation.varname]
            else:  # continue as if no dtype had been specified at all
                dtype = None

        # Use default dtypes (or a provided standard dtype for floats)
        if equation.var_type == BOOLEAN:
            return bool
        elif equation.var_type == INTEGER:
            return prefs["core.default_integer_dtype"]
        elif equation.var_type == FLOAT:
            if dtype is not None:
                dtype = np.dtype(dtype)
                if not dtype.kind == "f":
                    raise TypeError(f"{dtype} is not a valid floating point dtype.")
                return dtype
            else:
                return prefs["core.default_float_dtype"]
        else:
            raise ValueError(
                "Do not know how to determine a dtype for "
                f"variable '{equation.varname}' of type {equation.var_type}"
            )

    def _same_value(obj1, obj2):
        """
        Helper function used during namespace resolution.
        """
        if obj1 is obj2:
            return True
        try:
            obj1 = obj1.get_value()
        except (AttributeError, TypeError):
            pass

        try:
            obj2 = obj2.get_value()
        except (AttributeError, TypeError):
            pass

        return obj1 is obj2

    def _same_function(func1, func2):
        """
        Helper function, used during namespace resolution for comparing whether to
        functions are the same. This takes care of treating a function and a
        `Function` variables whose `Function.pyfunc` attribute matches as the
        same. This prevents the user from getting spurious warnings when having
        for example a numpy function such as :np:func:`~random.randn` in the local
        namespace, while the ``randn`` symbol in the numpy namespace used for the
        code objects refers to a `RandnFunction` specifier.
        """
        # use the function itself if it doesn't have a pyfunc attribute
        func1 = getattr(func1, "pyfunc", func1)
        func2 = getattr(func2, "pyfunc", func2)

        return func1 is func2

    class Indexing:
        """
        Object responsible for calculating flat index arrays from arbitrary group-
        specific indices. Stores strong references to the necessary variables so
        that basic indexing (i.e. slicing, integer arrays/values, ...) works even
        when the respective `VariableOwner` no longer exists. Note that this object
        does not handle string indexing.
        """

        def __init__(self, group, default_index="_idx"):
            self.group = weakref.proxy(group)
            self.N = group.variables["N"]
            self.default_index = default_index

        def __call__(self, item=slice(None), index_var=None):  # noqa: B008
            """
            Return flat indices to index into state variables from arbitrary
            group specific indices. In the default implementation, raises an error
            for multidimensional indices and transforms slices into arrays.

            Parameters
            ----------
            item : slice, array, int
                The indices to translate.

            Returns
            -------
            indices : `numpy.ndarray`
                The flat indices corresponding to the indices given in `item`.

            See Also
            --------
            SynapticIndexing
            """
            if index_var is None:
                index_var = self.default_index

            if hasattr(item, "_indices"):
                item = item._indices()

            if isinstance(item, tuple):
                raise IndexError(
                    f"Can only interpret 1-d indices, got {len(item)} dimensions."
                )
            else:
                if isinstance(item, str) and item == "True":
                    item = slice(None)
                if isinstance(item, slice):
                    if index_var == "0":
                        return 0
                    if index_var == "_idx":
                        start, stop, step = item.indices(self.N.item())
                    else:
                        start, stop, step = item.indices(index_var.size)
                    index_array = np.arange(start, stop, step, dtype=np.int32)
                else:
                    index_array = np.asarray(item)
                    if index_array.dtype == bool:
                        index_array = np.nonzero(index_array)[0]
                    elif not np.issubdtype(index_array.dtype, np.signedinteger):
                        raise TypeError(
                            "Indexing is only supported for integer "
                            "and boolean arrays, not for type "
                            f"{index_array.dtype}"
                        )

                if index_var != "_idx":
                    try:
                        return index_var.get_value()[index_array]
                    except IndexError as ex:
                        # We try to emulate numpy's indexing semantics here:
                        # slices never lead to IndexErrors, instead they return an
                        # empty array if they don't match anything
                        if isinstance(item, slice):
                            return np.array([], dtype=np.int32)
                        else:
                            raise ex
                else:
                    return index_array

    class IndexWrapper:
        """
        Convenience class to allow access to the indices via indexing syntax. This
        allows for example to get all indices for synapses originating from neuron
        10 by writing `synapses.indices[10, :]` instead of
        `synapses._indices.((10, slice(None))`.
        """

        def __init__(self, group):
            self.group = weakref.proxy(group)
            self.indices = group._indices

        def __getitem__(self, item):
            if isinstance(item, str):
                variables = Variables(None)
                variables.add_auxiliary_variable("_indices", dtype=np.int32)
                variables.add_auxiliary_variable("_cond", dtype=bool)

                abstract_code = f"_cond = {item}"
                namespace = get_local_namespace(level=1)
                from brian2.devices.device import get_device

                device = get_device()
                codeobj = create_runner_codeobj(
                    self.group,
                    abstract_code,
                    "group_get_indices",
                    run_namespace=namespace,
                    additional_variables=variables,
                    codeobj_class=device.code_object_class(
                        fallback_pref="codegen.string_expression_target"
                    ),
                )
                return codeobj()
            else:
                return self.indices(item)

    class VariableOwner(Nameable):
        """
        Mix-in class for accessing arrays by attribute.

        # TODO: Overwrite the __dir__ method to return the state variables
        # (should make autocompletion work)
        """

        def _enable_group_attributes(self):
            if not hasattr(self, "variables"):
                raise ValueError(
                    "Classes derived from VariableOwner need a variables attribute."
                )
            if "N" not in self.variables:
                raise ValueError("Each VariableOwner needs an 'N' variable.")
            if not hasattr(self, "codeobj_class"):
                self.codeobj_class = None
            if not hasattr(self, "_indices"):
                self._indices = Indexing(self)
            if not hasattr(self, "indices"):
                self.indices = IndexWrapper(self)
            if not hasattr(self, "_stored_states"):
                self._stored_states = {}
            self._group_attribute_access_active = True

        def state(self, name, use_units=True, level=0):
            """
            Return the state variable in a way that properly supports indexing in
            the context of this group

            Parameters
            ----------
            name : str
                The name of the state variable
            use_units : bool, optional
                Whether to use the state variable's unit.
            level : int, optional
                How much farther to go down in the stack to find the namespace.
            Returns
            -------
            var : `VariableView` or scalar value
                The state variable's value that can be indexed (for non-scalar
                values).
            """
            try:
                var = self.variables[name]
            except KeyError as exc:
                raise KeyError(f"State variable {name} not found.") from exc

            if use_units:
                return var.get_addressable_value_with_unit(name=name, group=self)
            else:
                return var.get_addressable_value(name=name, group=self)

        def __getattr__(self, name):
            # We do this because __setattr__ and __getattr__ are not active until
            # _group_attribute_access_active attribute is set, and if it is set,
            # then __getattr__ will not be called. Therefore, if getattr is called
            # with this name, it is because it hasn't been set yet and so this
            # method should raise an AttributeError to agree that it hasn't been
            # called yet.
            if name == "_group_attribute_access_active":
                raise AttributeError
            if "_group_attribute_access_active" not in self.__dict__:
                raise AttributeError
            if (
                name in self.__getattribute__("__dict__")
                or name in self.__getattribute__("__class__").__dict__
            ):
                # Makes sure that classes can override the "variables" mechanism
                # with instance/class attributes and properties
                return object.__getattribute__(self, name)
            # We want to make sure that accessing variables without units is fast
            # because this is what is used during simulations
            # We do not specifically check for len(name) here, we simply assume
            # that __getattr__ is not called with an empty string (which wouldn't
            # be possible using the normal dot syntax, anyway)
            try:
                if name[-1] == "_":
                    name = name[:-1]
                    use_units = False
                else:
                    use_units = True
                return self.state(name, use_units)

            except KeyError as ex:
                raise AttributeError(f"No attribute with name {name}") from ex

        def __setattr__(self, key, value, level=0):
            # attribute access is switched off until this attribute is created by
            # _enable_group_attributes
            if not hasattr(self, "_group_attribute_access_active") or key in self.__dict__:
                object.__setattr__(self, key, value)
            elif key in getattr(self, "_linked_variables", set()):
                if not isinstance(value, LinkedVariable):
                    raise ValueError(
                        "Cannot set a linked variable directly, link "
                        "it to another variable using 'linked_var'."
                    )
                linked_var = value.variable

                eq = self.equations[key]
                if eq.dim is not linked_var.dim:
                    raise DimensionMismatchError(
                        f"Unit of variable '{key}' does not "
                        "match its link target "
                        f"'{linked_var.name}'"
                    )

                if not isinstance(linked_var, Subexpression):
                    var_length = len(linked_var)
                else:
                    var_length = len(linked_var.owner)

                if value.index is not None:
                    index = self._linked_var_index(key, value, var_length)
                else:
                    index = self._linked_var_automatic_index(key, value, var_length)
                self.variables.add_reference(key, value.group, value.name, index=index)
                source = (value.variable.owner.name,)
                sourcevar = value.variable.name
                log_msg = f"Setting {self.name}.{key} as a link to {source}.{sourcevar}"
                if index is not None:
                    log_msg += f'(using "{index}" as index variable)'
                logger.diagnostic(log_msg)
            else:
                if isinstance(value, LinkedVariable):
                    raise TypeError(
                        f"Cannot link variable '{key}', it has to be marked "
                        "as a linked variable with '(linked)' in the model "
                        "equations."
                    )
                else:
                    if (
                        key in self.__getattribute__("__dict__")
                        or key in self.__getattribute__("__class__").__dict__
                    ):
                        # Makes sure that classes can override the "variables" mechanism
                        # with instance/class attributes and properties
                        return object.__setattr__(self, key, value)
                    elif key in self.variables:
                        var = self.variables[key]
                        if not isinstance(value, str):
                            if var.dim is DIMENSIONLESS:
                                fail_for_dimension_mismatch(
                                    value,
                                    var.dim,
                                    "%s should be set with a dimensionless value, but got {value}"
                                    % key,
                                    value=value,
                                )
                            else:
                                fail_for_dimension_mismatch(
                                    value,
                                    var.dim,
                                    "%s should be set with a value with units %r, but got {value}"
                                    % (key, get_unit(var.dim)),
                                    value=value,
                                )
                        if var.read_only:
                            raise TypeError(f"Variable {key} is read-only.")
                        # Make the call X.var = ... equivalent to X.var[:] = ...
                        var.get_addressable_value_with_unit(key, self).set_item(
                            slice(None), value, level=level + 1
                        )
                    elif len(key) and key[-1] == "_" and key[:-1] in self.variables:
                        # no unit checking
                        var = self.variables[key[:-1]]
                        if var.read_only:
                            raise TypeError(f"Variable {key[:-1]} is read-only.")
                        # Make the call X.var = ... equivalent to X.var[:] = ...
                        var.get_addressable_value(key[:-1], self).set_item(
                            slice(None), value, level=level + 1
                        )
                    elif hasattr(self, key) or key.startswith("_"):
                        object.__setattr__(self, key, value)
                    else:
                        # Try to suggest the correct name in case of a typo
                        checker = SpellChecker(
                            [
                                varname
                                for varname, var in self.variables.items()
                                if not (varname.startswith("_") or var.read_only)
                            ]
                        )
                        if key.endswith("_"):
                            suffix = "_"
                            key = key[:-1]
                        else:
                            suffix = ""
                        error_msg = f'Could not find a state variable with name "{key}".'
                        suggestions = checker.suggest(key)
                        if len(suggestions) == 1:
                            (suggestion,) = suggestions
                            error_msg += f' Did you mean to write "{suggestion}{suffix}"?'
                        elif len(suggestions) > 1:
                            suggestion_str = ", ".join(
                                [f"'{suggestion}{suffix}'" for suggestion in suggestions]
                            )
                            error_msg += f" Did you mean to write any of the following: {suggestion_str} ?"
                        error_msg += (
                            " Use the add_attribute method if you intend to add "
                            "a new attribute to the object."
                        )
                        raise AttributeError(error_msg)

        def _linked_var_automatic_index(self, var_name, linked_var, var_length):
            # The check at the end is to avoid the case that a size 1 NeuronGroup
            # links to another NeuronGroup of size 1 and cannot do certain operations
            # since the linked variable is considered scalar.
            if linked_var.variable.scalar or (
                var_length == 1 and getattr(self, "_N", 0) != 1
            ):
                index = "0"
            else:
                index = linked_var.group.variables.indices[linked_var.name]
                if index == "_idx":
                    target_length = var_length
                else:
                    target_length = len(linked_var.group.variables[index])
                    # we need a name for the index that does not clash with
                    # other names and a reference to the index
                    new_index = f"_{linked_var.name}_index_{index}"
                    self.variables.add_reference(new_index, linked_var.group, index)
                    index = new_index

                if len(self) != target_length:
                    raise ValueError(
                        f"Cannot link variable '{var_name}' to "
                        f"'{linked_var.variable.name}', the size of the "
                        "target group does not match "
                        f"({len(self)} != {target_length}). You can "
                        "provide an indexing scheme with the "
                        "'index' keyword to link groups with "
                        "different sizes"
                    )
            return index

        def _linked_var_index(self, var_name, linked_var, target_size):
            if isinstance(linked_var.index, str):
                if linked_var.index not in self.variables:
                    raise ValueError(f"Index variable '{linked_var.index}' not found.")
                if self.variables.indices[linked_var.index] != self.variables.default_index:
                    raise ValueError(
                        f"Index variable '{linked_var.index}' should use the default index itself."
                    )
                if not np.issubdtype(self.variables[linked_var.index].dtype, np.integer):
                    raise TypeError(
                        f"Index variable '{linked_var.index}' should be an integer parameter."
                    )
                index = linked_var.index
            else:
                # Index arrays are not allowed for classes with dynamic size (Synapses)
                if not isinstance(self.variables["N"], Constant):
                    raise TypeError(
                        "Cannot link a variable with an index array for a class with dynamic size – use a variable name instead."
                    )
                try:
                    index_array = np.asarray(linked_var.index)
                    if not np.issubdtype(index_array.dtype, int):
                        raise TypeError()
                except TypeError:
                    raise TypeError(
                        "The index for a linked variable has to be an integer array"
                    ) from None
                size = len(index_array)
                source_index = linked_var.group.variables.indices[linked_var.name]
                if source_index not in ("_idx", "0"):
                    # we are indexing into an already indexed variable,
                    # calculate the indexing into the target variable
                    index_array = linked_var.group.variables[source_index].get_value()[
                        index_array
                    ]

                if not index_array.ndim == 1 or size != len(self):
                    raise TypeError(
                        f"Index array for linked variable '{var_name}' "
                        "has to be a one-dimensional array of "
                        f"length {len(self)}, but has shape "
                        f"{index_array.shape!s}"
                    )
                if min(index_array) < 0 or max(index_array) >= target_size:
                    raise ValueError(
                        f"Index array for linked variable {var_name} "
                        "contains values outside of the valid "
                        f"range [0, {target_size}["
                    )
                self.variables.add_array(
                    f"_{var_name}_indices",
                    size=size,
                    dtype=index_array.dtype,
                    constant=True,
                    read_only=True,
                    values=index_array,
                )
                index = f"_{var_name}_indices"
            return index

        def add_attribute(self, name):
            """
            Add a new attribute to this group. Using this method instead of simply
            assigning to the new attribute name is necessary because Brian will
            raise an error in that case, to avoid bugs passing unnoticed
            (misspelled state variable name, un-declared state variable, ...).

            Parameters
            ----------
            name : str
                The name of the new attribute

            Raises
            ------
            AttributeError
                If the name already exists as an attribute or a state variable.
            """
            if name in self.variables:
                raise AttributeError(
                    f'Cannot add an attribute "{name}", it is already a state variable of'
                    " this group."
                )
            if hasattr(self, name):
                raise AttributeError(
                    f'Cannot add an attribute "{name}", it is already an attribute of this'
                    " group."
                )
            object.__setattr__(self, name, None)

        def get_states(
            self,
            vars=None,
            units=True,
            format="dict",
            subexpressions=False,
            read_only_variables=True,
            level=0,
        ):
            """
            Return a copy of the current state variable values. The returned arrays
            are copies of the actual arrays that store the state variable values,
            therefore changing the values in the returned dictionary will not affect
            the state variables.

            Parameters
            ----------
            vars : list of str, optional
                The names of the variables to extract. If not specified, extract
                all state variables (except for internal variables, i.e. names that
                start with ``'_'``). If the ``subexpressions`` argument is ``True``,
                the current values of all subexpressions are returned as well.
            units : bool, optional
                Whether to include the physical units in the return value. Defaults
                to ``True``.
            format : str, optional
                The output format. Defaults to ``'dict'``.
            subexpressions: bool, optional
                Whether to return subexpressions when no list of variable names
                is given. Defaults to ``False``. This argument is ignored if an
                explicit list of variable names is given in ``vars``.
            read_only_variables : bool, optional
                Whether to return read-only variables (e.g. the number of neurons,
                the time, etc.). Setting it to ``False`` will assure that the
                returned state can later be used with `set_states`. Defaults to
                ``True``.
            level : int, optional
                How much higher to go up the stack to resolve external variables.
                Only relevant if extracting subexpressions that refer to external
                variables.

            Returns
            -------
            values : dict or specified format
                The variables specified in ``vars``, in the specified ``format``.

            """
            if format not in ImportExport.methods:
                raise NotImplementedError(f"Format '{format}' is not supported")
            if vars is None:
                vars = []
                for name, var in self.variables.items():
                    if name.startswith("_"):
                        continue
                    if subexpressions or not isinstance(var, Subexpression):
                        if read_only_variables or not getattr(var, "read_only", False):
                            if not isinstance(var, AuxiliaryVariable):
                                vars.append(name)
            data = ImportExport.methods[format].export_data(
                self, vars, units=units, level=level
            )
            return data

        def set_states(self, values, units=True, format="dict", level=0):
            """
            Set the state variables.

            Parameters
            ----------
            values : depends on ``format``
                The values according to ``format``.
            units : bool, optional
                Whether the ``values`` include physical units. Defaults to ``True``.
            format : str, optional
                The format of ``values``. Defaults to ``'dict'``
            level : int, optional
                How much higher to go up the stack to resolve external variables.
                Only relevant when using string expressions to set values.
            """
            # For the moment, 'dict' is the only supported format -- later this will
            # be made into an extensible system, see github issue #306
            if format not in ImportExport.methods:
                raise NotImplementedError(f"Format '{format}' is not supported")
            ImportExport.methods[format].import_data(self, values, units=units, level=level)

        def check_variable_write(self, variable):
            """
            Function that can be overwritten to raise an error if writing to a
            variable should not be allowed. Note that this does *not* deal with
            incorrect writes that are general to all kind of variables (incorrect
            units, writing to a read-only variable, etc.). This function is only
            used for type-specific rules, e.g. for raising an error in `Synapses`
            when writing to a synaptic variable before any `~Synapses.connect`
            call.

            By default this function does nothing.

            Parameters
            ----------
            variable : `Variable`
                The variable that the user attempts to set.
            """
            pass

        def _full_state(self):
            state = {}
            for var in self.variables.values():
                if not isinstance(var, ArrayVariable):
                    continue  # we are only interested in arrays
                if var.owner is None or var.owner.name != self.name:
                    continue  # we only store the state of our own variables

                state[var.name] = (var.get_value().copy(), var.size)

            return state

        def _restore_from_full_state(self, state):
            for var_name, (values, size) in state.items():
                var = self.variables[var_name]
                if isinstance(var, DynamicArrayVariable):
                    var.resize(size)
                var.set_value(values)

        def _check_expression_scalar(self, expr, varname, level=0, run_namespace=None):
            """
            Helper function to check that an expression only refers to scalar
            variables, used when setting a scalar variable with a string expression.

            Parameters
            ----------
            expr : str
                The expression to check.
            varname : str
                The variable that is being set (only used for the error message)
            level : int, optional
                How far to go up in the stack to find the local namespace (if
                `run_namespace` is not set).
            run_namespace : dict-like, optional
                A specific namespace provided for this expression.

            Raises
            ------
            ValueError
                If the expression refers to a non-scalar variable.
            """
            identifiers = get_identifiers(expr)
            referred_variables = self.resolve_all(
                identifiers, run_namespace=run_namespace, level=level + 1
            )
            for ref_varname, ref_var in referred_variables.items():
                if not getattr(ref_var, "scalar", False):
                    raise ValueError(
                        "String expression for setting scalar "
                        f"variable '{varname} refers to '{ref_varname} which "
                        "is not scalar."
                    )

        def __len__(self):
            return self.variables["N"].item()

    class Group(VariableOwner, BrianObject):
        def _resolve(
            self, identifier, run_namespace, user_identifier=True, additional_variables=None
        ):
            """
            Resolve an identifier (i.e. variable, constant or function name) in the
            context of this group. This function will first lookup the name in the
            state variables, then look for a standard function or unit of that
            name and finally look in `Group.namespace` and in `run_namespace`. If
            the latter is not given, it will try to find the variable in the local
            namespace where the original function call took place. See
            :ref:`external-variables`.

            Parameters
            ----------
            identifiers : str
                The name to look up.
            run_namespace : dict-like, optional
                An additional namespace that is used for variable lookup (if not
                defined, the implicit namespace of local variables is used).
            user_identifier : bool, optional
                Whether this is an identifier that was used by the user (and not
                something automatically generated that the user might not even
                know about). Will be used to determine whether to display a
                warning in the case of namespace clashes. Defaults to ``True``.
            additional_variables : dict-like, optional
                An additional mapping of names to `Variable` objects that will be
                checked before `Group.variables`.

            Returns
            -------
            obj : `Variable` or `Function`
                Returns a `Variable` object describing the variable or a `Function`
                object for a function. External variables are represented as
                `Constant` objects

            Raises
            ------
            KeyError
                If the `identifier` could not be resolved
            """
            resolved_internal = None

            if identifier in (additional_variables or {}):
                resolved_internal = additional_variables[identifier]
            elif identifier in getattr(self, "variables", {}):
                resolved_internal = self.variables[identifier]

            if resolved_internal is not None:
                if not user_identifier:
                    return resolved_internal  # no need to go further
                # We already found the identifier, but we try to resolve it in the
                # external namespace nevertheless, to report a warning if it is
                # present there as well.
                self._resolve_external(
                    identifier,
                    run_namespace=run_namespace,
                    internal_variable=resolved_internal,
                )
                return resolved_internal

            # We did not find the name internally, try to resolve it in the external
            # namespace
            return self._resolve_external(identifier, run_namespace=run_namespace)

        def resolve_all(
            self,
            identifiers,
            run_namespace,
            user_identifiers=None,
            additional_variables=None,
        ):
            """
            Resolve a list of identifiers. Calls `Group._resolve` for each
            identifier.

            Parameters
            ----------
            identifiers : iterable of str
                The names to look up.
            run_namespace : dict-like, optional
                An additional namespace that is used for variable lookup (if not
                defined, the implicit namespace of local variables is used).
            user_identifiers : iterable of str, optional
                The names in ``identifiers`` that were provided by the user (i.e.
                are part of user-specified equations, abstract code, etc.). Will
                be used to determine when to issue namespace conflict warnings. If
                not specified, will be assumed to be identical to ``identifiers``.
            additional_variables : dict-like, optional
                An additional mapping of names to `Variable` objects that will be
                checked before `Group.variables`.

            Returns
            -------
            variables : dict of `Variable` or `Function`
                A mapping from name to `Variable`/`Function` object for each of the
                names given in `identifiers`

            Raises
            ------
            KeyError
                If one of the names in `identifier` cannot be resolved
            """
            if user_identifiers is None:
                user_identifiers = identifiers
            assert isinstance(run_namespace, Mapping)
            resolved = {}
            for identifier in identifiers:
                resolved[identifier] = self._resolve(
                    identifier,
                    user_identifier=identifier in user_identifiers,
                    additional_variables=additional_variables,
                    run_namespace=run_namespace,
                )
            return resolved

        def _resolve_external(
            self, identifier, run_namespace, user_identifier=True, internal_variable=None
        ):
            """
            Resolve an external identifier in the context of a `Group`. If the `Group`
            declares an explicit namespace, this namespace is used in addition to the
            standard namespace for units and functions. Additionally, the namespace in
            the `run_namespace` argument (i.e. the namespace provided to `Network.run`)
            is used.

            Parameters
            ----------
            identifier : str
                The name to resolve.
            group : `Group`
                The group that potentially defines an explicit namespace for looking up
                external names.
            run_namespace : dict
                A namespace (mapping from strings to objects), as provided as an
                argument to the `Network.run` function or returned by
                `get_local_namespace`.
            user_identifier : bool, optional
                Whether this is an identifier that was used by the user (and not
                something automatically generated that the user might not even
                know about). Will be used to determine whether to display a
                warning in the case of namespace clashes. Defaults to ``True``.
            internal_variable : `Variable`, optional
                The internal variable object that corresponds to this name (if any).
                This is used to give warnings if it also corresponds to a variable
                from an external namespace.
            """
            # We save tuples of (namespace description, referred object) to
            # give meaningful warnings in case of duplicate definitions
            matches = []

            namespaces = OrderedDict()
            # Default namespaces (units and functions)
            namespaces["constants"] = DEFAULT_CONSTANTS
            namespaces["units"] = DEFAULT_UNITS
            namespaces["functions"] = DEFAULT_FUNCTIONS
            if getattr(self, "namespace", None) is not None:
                namespaces["group-specific"] = self.namespace

            # explicit or implicit run namespace
            namespaces["run"] = run_namespace

            for description, namespace in namespaces.items():
                if identifier in namespace:
                    match = namespace[identifier]
                    if (
                        isinstance(
                            match,
                            (numbers.Number, np.ndarray, np.generic, Function, Variable),
                        )
                    ) or (
                        inspect.isfunction(match)
                        and hasattr(match, "_arg_units")
                        and hasattr(match, "_return_unit")
                    ):
                        matches.append((description, match))

            if len(matches) == 0:
                # No match at all
                if internal_variable is not None:
                    return None
                else:
                    # Give a more detailed explanation for the lastupdate variable
                    # that was removed with PR #1003
                    if identifier == "lastupdate":
                        error_msg = (
                            'The identifier "lastupdate" could not be '
                            "resolved. Note that this variable is only "
                            "automatically defined for models with "
                            "event-driven synapses. You can define it "
                            'manually by adding "lastupdate : second" to '
                            'the equations and setting "lastupdate = t" '
                            "at the end of your on_pre and/or on_post "
                            "statements."
                        )
                    else:
                        error_msg = f'The identifier "{identifier}" could not be resolved.'
                    raise KeyError(error_msg)

            elif len(matches) > 1:
                # Possibly, all matches refer to the same object
                first_obj = matches[0][1]
                found_mismatch = False
                for m in matches:
                    if _same_value(m[1], first_obj):
                        continue
                    if _same_function(m[1], first_obj):
                        continue
                    try:
                        proxy = weakref.proxy(first_obj)
                        if m[1] is proxy:
                            continue
                    except TypeError:
                        pass

                    # Found a mismatch
                    found_mismatch = True
                    break

                if found_mismatch and user_identifier and internal_variable is None:
                    _conflict_warning(
                        'The name "%s" refers to different objects '
                        "in different namespaces used for resolving "
                        'names in the context of group "%s". '
                        "Will use the object from the %s namespace "
                        "with the value %s,"
                        % (
                            identifier,
                            getattr(self, "name", "<unknown>"),
                            matches[0][0],
                            _display_value(first_obj),
                        ),
                        matches[1:],
                    )

            if internal_variable is not None and user_identifier:
                # Filter out matches that are identical (a typical case being an
                # externally defined "N" with the the number of neurons and a later
                # use of "N" in an expression (which refers to the internal variable
                # storing the number of neurons in the group)
                if isinstance(internal_variable, Constant):
                    filtered_matches = []
                    for match in matches:
                        if not _same_value(match[1], internal_variable):
                            filtered_matches.append(match)
                else:
                    filtered_matches = matches
                if len(filtered_matches) == 0:
                    pass  # Nothing to warn about
                else:
                    warning_message = (
                        f"'{identifier}' is an internal variable of group "
                        f"'{self.name}', but also exists in the "
                    )
                    if len(matches) == 1:
                        namespace = filtered_matches[0][0]
                        value = _display_value(filtered_matches[0][1])
                        warning_message += f"{namespace} namespace with the value {value}. "
                    else:
                        namespaces_list = " ,".join(match[0] for match in filtered_matches)
                        warning_message += f"following namespaces: {namespaces_list}. "
                    warning_message += "The internal variable will be used."
                    logger.warn(
                        warning_message, "Group.resolve.resolution_conflict", once=True
                    )

            if internal_variable is not None:
                return None  # We were only interested in the warnings above

            # use the first match (according to resolution order)
            resolved = matches[0][1]

            # Replace pure Python functions by a Functions object
            if callable(resolved) and not isinstance(resolved, Function):
                resolved = Function(
                    resolved,
                    arg_units=getattr(resolved, "_arg_units", None),
                    arg_names=getattr(resolved, "_arg_names", None),
                    return_unit=getattr(resolved, "_return_unit", None),
                    stateless=getattr(resolved, "stateless", False),
                )

            if not isinstance(resolved, (Function, Variable)):
                # Wrap the value in a Constant object
                dimensions = getattr(resolved, "dim", DIMENSIONLESS)
                value = np.asarray(resolved)
                if value.shape != ():
                    raise KeyError(
                        f"Variable {identifier} was found in the namespace, but is not a"
                        " scalar value"
                    )
                resolved = Constant(identifier, dimensions=dimensions, value=value)

            return resolved

        def runner(self, *args, **kwds):
            raise AttributeError("The 'runner' method has been renamed to 'run_regularly'.")

        def custom_operation(self, *args, **kwds):
            raise AttributeError(
                "The 'custom_operation' method has been renamed to 'run_regularly'."
            )

        def run_regularly(
            self,
            code,
            dt=None,
            clock=None,
            when="start",
            order=0,
            name=None,
            codeobj_class=None,
        ):
            """
            Run abstract code in the group's namespace. The created `CodeRunner`
            object will be automatically added to the group, it therefore does not
            need to be added to the network manually. However, a reference to the
            object will be returned, which can be used to later remove it from the
            group or to set it to inactive.

            Parameters
            ----------
            code : str
                The abstract code to run.
            dt : `Quantity`, optional
                The time step to use for this custom operation. Cannot be combined
                with the `clock` argument.
            clock : `Clock`, optional
                The update clock to use for this operation. If neither a clock nor
                the `dt` argument is specified, defaults to the clock of the group.
            when : str, optional
                When to run within a time step, defaults to the ``'start'`` slot.
                See :ref:`scheduling` for possible values.
            name : str, optional
                A unique name, if non is given the name of the group appended with
                'run_regularly', 'run_regularly_1', etc. will be used. If a
                name is given explicitly, it will be used as given (i.e. the group
                name will not be prepended automatically).
            codeobj_class : class, optional
                The `CodeObject` class to run code with. If not specified, defaults
                to the `group`'s ``codeobj_class`` attribute.

            Returns
            -------
            obj : `CodeRunner`
                A reference to the object that will be run.
            """
            from brian2.core.clocks import Clock  # Avoid circular import

            if name is None:
                names = [o.name for o in self.contained_objects]
                name = find_name(f"{self.name}_run_regularly*", names)

            if dt is None and clock is None:
                clock = self._clock
            elif clock is None:
                clock = Clock(dt=dt, name=f"{name}_clock*")

            return self.run_on_clock(code, clock, when, order, name, codeobj_class)

        def run_on_clock(
            self,
            code,
            clock=None,
            when="start",
            order=0,
            name=None,
            codeobj_class=None,
        ):
            """
            This method is used by `run_regularly` and `run_at` to register operations
            that are executed at times determined by a user-supplied or internally generated `Clock`.
            The resulting `CodeRunner` is automatically added to the group.

            Parameters
            ----------
            code : str
                The abstract code to run.
            clock : `Clock`, optional
                The update clock to use for this operation. If neither a clock nor
                the `dt` argument is specified, defaults to the clock of the group.
            when : str, optional
                When to run within a time step, defaults to the ``'start'`` slot.
                See :ref:`scheduling` for possible values.
            name : str, optional
                A unique name, if non is given the name of the group appended with
                'run_custom_clock', 'run_custom_clock_1', etc. will be used. If a
                name is given explicitly, it will be used as given (i.e. the group
                name will not be prepended automatically).
            codeobj_class : class, optional
                The `CodeObject` class to run code with. If not specified, defaults
                to the `group`'s ``codeobj_class`` attribute.

            Returns
            -------
            obj : `CodeRunner`
                A reference to the object that will be run.
            """
            if name is None:
                names = [o.name for o in self.contained_objects]
                name = find_name(f"{self.name}_run_custom*", names)

            # Subgroups are normally not included in their parent's
            # contained_objects list, since there's no need to include them in the
            # network (they don't perform any computation on their own). However,
            # if a subgroup declares a `run_regularly` operation, then we want to
            # include this operation automatically, i.e. with the parent group
            # (adding just the run_regularly operation to the parent group's
            # contained objects would no be enough, since the CodeObject needs a
            # reference to the group providing the context for the operation, i.e.
            # the subgroup instead of the parent group. See github issue #922
            source_group = getattr(self, "source", None)
            if source_group is not None:
                if self not in source_group.contained_objects:
                    source_group.contained_objects.append(self)

            runner = CodeRunner(
                self,
                "stateupdate",
                code=code,
                name=name,
                clock=clock,
                when=when,
                order=order,
                codeobj_class=codeobj_class,
            )
            self.contained_objects.append(runner)
            return runner

        def run_at(
            self,
            code,
            times,
            when="start",
            order=0,
            name=None,
            codeobj_class=None,
        ):
            """
            Run abstract code in the group's namespace. The created `CodeRunner`
            object will be automatically added to the group, it therefore does not
            need to be added to the network manually. However, a reference to the
            object will be returned, which can be used to later remove it from the
            group or to set it to inactive.

            Parameters
            ----------
            code : str
                The abstract code to run.
            times : array-like
                The specific simulation times at which to execute the code.
            when : str, optional
                When to run within a time step, defaults to the ``'start'`` slot.
                See :ref:`scheduling` for possible values.
            name : str, optional
                A unique name, if non is given the name of the group appended with
                'run_at', 'run_at_1', etc. will be used. If a
                name is given explicitly, it will be used as given (i.e. the group
                name will not be prepended automatically).
            codeobj_class : class, optional
                The `CodeObject` class to run code with. If not specified, defaults
                to the `group`'s ``codeobj_class`` attribute.

            Returns
            -------
            obj : `CodeRunner`
                A reference to the object that will be run.
            """
            if name is None:
                names = [o.name for o in self.contained_objects]
                name = find_name(f"{self.name}_run_at*", names)
            from brian2.core.clocks import EventClock

            clock = EventClock(times, name=f"{name}_eventclock*")
            return self.run_on_clock(code, clock, when, order, name, codeobj_class)

        def _check_for_invalid_states(self):
            """
            Checks if any state variables updated by differential equations have
            invalid values, and logs a warning if so.
            """
            equations = getattr(self, "equations", None)
            if not isinstance(equations, Equations):
                return
            for varname in equations.diff_eq_names:
                self._check_for_invalid_values(
                    varname, self.state(varname, use_units=False)
                )

        def _check_for_invalid_values(self, k, v):
            """
            Checks if variable named k value v has invalid values, and logs a
            warning if so.
            """
            v = np.asarray(v)
            if np.isnan(v).any() or (np.abs(v) > 1e50).any():
                logger.warn(
                    f"{self.name}'s variable '{k}' has NaN, very large values, "
                    "or encountered an error in numerical integration. "
                    "This is usually a sign that an unstable or invalid "
                    "integration method was "
                    "chosen.",
                    name_suffix="invalid_values",
                    once=True,
                )

    class CodeRunner(BrianObject):
        """
        A "code runner" that runs a `CodeObject` every timestep and keeps a
        reference to the `Group`. Used in `NeuronGroup` for `Thresholder`,
        `Resetter` and `StateUpdater`.

        On creation, we try to run the before_run method with an empty additional
        namespace (see `Network.before_run`). If the namespace is already complete
        this might catch unit mismatches.

        Parameters
        ----------
        group : `Group`
            The group to which this object belongs.
        template : `Template`
            The template that should be used for code generation
        code : str, optional
            The abstract code that should be executed every time step. The
            `update_abstract_code` method might generate this code dynamically
            before every run instead.
        dt : `Quantity`, optional
            The time step to be used for the simulation. Cannot be combined with
            the `clock` argument.
        user_code : str, optional
            The abstract code as specified by the user, i.e. without any additions
            of internal code that the user not necessarily knows about. This will
            be used for warnings and error messages.
        clock : `Clock`, optional
            The update clock to be used. If neither a clock, nor the `dt` argument
            is specified, the `defaultclock` will be used.
        when : str, optional
            In which scheduling slot to execute the operation during a time step.
            Defaults to ``'start'``. See :ref:`scheduling` for possible values.
        order : int, optional
            The priority of this operation for operations occurring at the same time
            step and in the same scheduling slot. Defaults to 0.
        name : str, optional
            The name for this object.
        check_units : bool, optional
            Whether the units should be checked for consistency before a run. Is
            activated (``True``) by default but should be switched off for state
            updaters (units are already checked for the equations and the generated
            abstract code might have already replaced variables with their unit-less
            values)
        template_kwds : dict, optional
            A dictionary of additional information that is passed to the template.
        needed_variables: list of str, optional
            A list of variables that are neither present in the abstract code, nor
            in the ``USES_VARIABLES`` statement in the template. This is only
            rarely necessary, an example being a `StateMonitor` where the
            names of the variables are neither known to the template nor included
            in the abstract code statements.
        override_conditional_write: list of str, optional
            A list of variable names which are used as conditions (e.g. for
            refractoriness) which should be ignored.
        codeobj_class : class, optional
            The `CodeObject` class to run code with. If not specified, defaults to
            the `group`'s ``codeobj_class`` attribute.
        generate_empty_code : bool, optional
            Whether to generate a `CodeObject` if there is no abstract code to
            execute. Defaults to ``True`` but should be switched off e.g. for a
            `StateUpdater` when there is nothing to do.
        """

        add_to_magic_network = True
        invalidates_magic_network = True

        def __init__(
            self,
            group,
            template,
            code="",
            user_code=None,
            dt=None,
            clock=None,
            when="start",
            order=0,
            name="coderunner*",
            check_units=True,
            template_kwds=None,
            needed_variables=None,
            override_conditional_write=None,
            codeobj_class=None,
            generate_empty_code=True,
        ):
            BrianObject.__init__(
                self, clock=clock, dt=dt, when=when, order=order, name=name
            )
            self.group = weakproxy_with_fallback(group)
            self.template = template
            self.user_code = user_code
            self.abstract_code = code
            self.check_units = check_units
            if needed_variables is None:
                needed_variables = []
            self.needed_variables = needed_variables
            self.template_kwds = template_kwds
            self.override_conditional_write = override_conditional_write
            if codeobj_class is None:
                codeobj_class = group.codeobj_class
            self.codeobj_class = codeobj_class
            self.generate_empty_code = generate_empty_code
            self.codeobj = None

        def __getstate__(self):
            state = self.__dict__.copy()
            state["group"] = state["group"].__repr__.__self__
            return state

        def __setstate__(self, state):
            state["group"] = weakproxy_with_fallback(state["group"])
            self.__dict__ = state

        def update_abstract_code(self, run_namespace):
            """
            Update the abstract code for the code object. Will be called in
            `before_run` and should update the `CodeRunner.abstract_code`
            attribute.

            Does nothing by default.
            """
            pass

        def create_default_code_object(self, run_namespace):
            self.update_abstract_code(run_namespace=run_namespace)
            # If the CodeRunner has variables, add them
            if hasattr(self, "variables"):
                additional_variables = self.variables
            else:
                additional_variables = None

            if not self.generate_empty_code and len(self.abstract_code) == 0:
                self.codeobj = None
            else:
                self.codeobj = create_runner_codeobj(
                    group=self.group,
                    code=self.abstract_code,
                    user_code=self.user_code,
                    template_name=self.template,
                    name=f"{self.name}_codeobject*",
                    check_units=self.check_units,
                    additional_variables=additional_variables,
                    needed_variables=self.needed_variables,
                    run_namespace=run_namespace,
                    template_kwds=self.template_kwds,
                    override_conditional_write=self.override_conditional_write,
                    codeobj_class=self.codeobj_class,
                )
            return self.codeobj

        def create_code_objects(self, run_namespace):
            # By default, we only have one code object for each CodeRunner.
            # Overwrite this function to use more than one.
            code_object = self.create_default_code_object(run_namespace)
            if code_object:
                self.code_objects[:] = [weakref.proxy(code_object)]
            else:
                self.code_objects[:] = []

        def before_run(self, run_namespace):
            self.create_code_objects(run_namespace)
            super().before_run(run_namespace)