hSrSSKrSSKrSSKrSSKrSSKrSSKJr SSKJ r SSK r SSK J r JrJr SSKJr S/r\R&"\5rS rS S .S jr\"S 5r0r0r0rSrSrSrSr"SS5r Sr!Sr"SSS.Sjr#SS.Sjr$"SS5r%\RLROS5(a\ r(SSjr \(RRR\ l\RT"\(RR5r+\+RY\+RZR]5VVs/sHupUS:wdM UPM snnS9\ l/ggs snnf) a\ Docs for backend users ~~~~~~~~~~~~~~~~~~~~~~ NetworkX utilizes a plugin-dispatch architecture. A valid NetworkX backend specifies `entry points `_, named ``networkx.backends`` and an optional ``networkx.backend_info`` when it is installed (not imported). This allows NetworkX to dispatch (redirect) function calls to the backend so the execution flows to the designated backend implementation. This design enhances flexibility and integration, making NetworkX more adaptable and efficient. NetworkX can dispatch to backends **explicitly** (this requires changing code) or **automatically** (this requires setting configuration or environment variables). The best way to use a backend depends on the backend, your use case, and whether you want to automatically convert to or from backend graphs. Automatic conversions of graphs is always opt-in. To explicitly dispatch to a backend, use the `backend=` keyword argument in a dispatchable function. This will convert (and cache by default) input NetworkX graphs to backend graphs and call the backend implementation. Another explicit way to use a backend is to create a backend graph directly--for example, perhaps the backend has its own functions for loading data and creating graphs--and pass that graph to a dispatchable function, which will then call the backend implementation without converting. Using automatic dispatch requires setting configuration options. Every NetworkX configuration may also be set from an environment variable and are processed at the time networkx is imported. The following configuration variables are supported: * ``nx.config.backend_priority`` (``NETWORKX_BACKEND_PRIORITY`` env var), a list of backends, controls dispatchable functions that don't return graphs such as e.g. ``nx.pagerank``. When one of these functions is called with NetworkX graphs as input, the dispatcher iterates over the backends listed in this backend_priority config and will use the first backend that implements this function. The input NetworkX graphs are converted (and cached by default) to backend graphs. Using this configuration can allow you to use the full flexibility of NetworkX graphs and the performance of backend implementations, but possible downsides are that creating NetworkX graphs, converting to backend graphs, and caching backend graphs may all be expensive. * ``nx.config.backend_priority.algos`` (``NETWORKX_BACKEND_PRIORITY_ALGOS`` env var), can be used instead of ``nx.config.backend_priority`` (``NETWORKX_BACKEND_PRIORITY`` env var) to emphasize that the setting only affects the dispatching of algorithm functions as described above. * ``nx.config.backend_priority.generators`` (``NETWORKX_BACKEND_PRIORITY_GENERATORS`` env var), a list of backends, controls dispatchable functions that return graphs such as nx.from_pandas_edgelist and nx.empty_graph. When one of these functions is called, the first backend listed in this backend_priority config that implements this function will be used and will return a backend graph. When this backend graph is passed to other dispatchable NetworkX functions, it will use the backend implementation if it exists or raise by default unless nx.config.fallback_to_nx is True (default is False). Using this configuration avoids creating NetworkX graphs, which subsequently avoids the need to convert to and cache backend graphs as when using nx.config.backend_priority.algos, but possible downsides are that the backend graph may not behave the same as a NetworkX graph and the backend may not implement all algorithms that you use, which may break your workflow. * ``nx.config.fallback_to_nx`` (``NETWORKX_FALLBACK_TO_NX`` env var), a boolean (default False), controls what happens when a backend graph is passed to a dispatchable function that is not implemented by that backend. The default behavior when False is to raise. If True, then the backend graph will be converted (and cached by default) to a NetworkX graph and will run with the default NetworkX implementation. Enabling this configuration can allow workflows to complete if the backend does not implement all algorithms used by the workflow, but a possible downside is that it may require converting the input backend graph to a NetworkX graph, which may be expensive. If a backend graph is duck-type compatible as a NetworkX graph, then the backend may choose not to convert to a NetworkX graph and use the incoming graph as-is. * ``nx.config.cache_converted_graphs`` (``NETWORKX_CACHE_CONVERTED_GRAPHS`` env var), a boolean (default True), controls whether graph conversions are cached to G.__networkx_cache__ or not. Caching can improve performance by avoiding repeated conversions, but it uses more memory. .. note:: Backends *should* follow the NetworkX backend naming convention. For example, if a backend is named ``parallel`` and specified using ``backend=parallel`` or ``NETWORKX_BACKEND_PRIORITY=parallel``, the package installed is ``nx-parallel``, and we would use ``import nx_parallel`` if we were to import the backend package directly. Backends are encouraged to document how they recommend to be used and whether their graph types are duck-type compatible as NetworkX graphs. If backend graphs are NetworkX-compatible and you want your workflow to automatically "just work" with a backend--converting and caching if necessary--then use all of the above configurations. Automatically converting graphs is opt-in, and configuration gives the user control. Examples: --------- Use the ``cugraph`` backend for every algorithm function it supports. This will allow for fall back to the default NetworkX implementations for algorithm calls not supported by cugraph because graph generator functions are still returning NetworkX graphs. .. code-block:: bash bash> NETWORKX_BACKEND_PRIORITY=cugraph python my_networkx_script.py Explicitly use the ``parallel`` backend for a function call. .. code-block:: python nx.betweenness_centrality(G, k=10, backend="parallel") Explicitly use the ``parallel`` backend for a function call by passing an instance of the backend graph type to the function. .. code-block:: python H = nx_parallel.ParallelGraph(G) nx.betweenness_centrality(H, k=10) Explicitly use the ``parallel`` backend and pass additional backend-specific arguments. Here, ``get_chunks`` is an argument unique to the ``parallel`` backend. .. code-block:: python nx.betweenness_centrality(G, k=10, backend="parallel", get_chunks=get_chunks) Automatically dispatch the ``cugraph`` backend for all NetworkX algorithms and generators, and allow the backend graph object returned from generators to be passed to NetworkX functions the backend does not support. .. code-block:: bash bash> NETWORKX_BACKEND_PRIORITY_ALGOS=cugraph \ NETWORKX_BACKEND_PRIORITY_GENERATORS=cugraph \ NETWORKX_FALLBACK_TO_NX=True \ python my_networkx_script.py How does this work? ------------------- If you've looked at functions in the NetworkX codebase, you might have seen the ``@nx._dispatchable`` decorator on most of the functions. This decorator allows the NetworkX function to dispatch to the corresponding backend function if available. When the decorated function is called, it first checks for a backend to run the function, and if no appropriate backend is specified or available, it runs the NetworkX version of the function. Backend Keyword Argument ^^^^^^^^^^^^^^^^^^^^^^^^ When a decorated function is called with the ``backend`` kwarg provided, it checks if the specified backend is installed, and loads it. Next it checks whether to convert input graphs by first resolving the backend of each input graph by looking for an attribute named ``__networkx_backend__`` that holds the backend name for that graph type. If all input graphs backend matches the ``backend`` kwarg, the backend's function is called with the original inputs. If any of the input graphs do not match the ``backend`` kwarg, they are converted to the backend graph type before calling. Exceptions are raised if any step is not possible, e.g. if the backend does not implement this function. Finding a Backend ^^^^^^^^^^^^^^^^^ When a decorated function is called without a ``backend`` kwarg, it tries to find a dispatchable backend function. The backend type of each input graph parameter is resolved (using the ``__networkx_backend__`` attribute) and if they all agree, that backend's function is called if possible. Otherwise the backends listed in the config ``backend_priority`` are considered one at a time in order. If that backend supports the function and can convert the input graphs to its backend type, that backend function is called. Otherwise the next backend is considered. During this process, the backends can provide helpful information to the dispatcher via helper methods in the backend's interface. Backend methods ``can_run`` and ``should_run`` are used by the dispatcher to determine whether to use the backend function. If the number of nodes is small, it might be faster to run the NetworkX version of the function. This is how backends can provide info about whether to run. Falling Back to NetworkX ^^^^^^^^^^^^^^^^^^^^^^^^ If none of the backends are appropriate, we "fall back" to the NetworkX function. That means we resolve the backends of all input graphs and if all are NetworkX graphs we call the NetworkX function. If any are not NetworkX graphs, we raise an exception unless the `fallback_to_nx` config is set. If it is, we convert all graph types to NetworkX graph types before calling the NetworkX function. Functions that mutate the graph ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Any function decorated with the option that indicates it mutates the graph goes through a slightly different path to automatically find backends. These functions typically generate a graph, or add attributes or change the graph structure. The config `backend_priority.generators` holds a list of backend names similar to the config `backend_priority`. The process is similar for finding a matching backend. Once found, the backend function is called and a backend graph is returned (instead of a NetworkX graph). You can then use this backend graph in any function supported by the backend. And you can use it for functions not supported by the backend if you set the config `fallback_to_nx` to allow it to convert the backend graph to a NetworkX graph before calling the function. Optional keyword arguments ^^^^^^^^^^^^^^^^^^^^^^^^^^ Backends can add optional keyword parameters to NetworkX functions to allow you to control aspects of the backend algorithm. Thus the function signatures can be extended beyond the NetworkX function signature. For example, the ``parallel`` backend might have a parameter to specify how many CPUs to use. These parameters are collected by the dispatchable decorator code at the start of the function call and used when calling the backend function. Existing Backends ^^^^^^^^^^^^^^^^^ NetworkX does not know all the backends that have been created. In fact, the NetworkX library does not need to know that a backend exists for it to work. As long as the backend package creates the ``entry_point``, and provides the correct interface, it will be called when the user requests it using one of the three approaches described above. Some backends have been working with the NetworkX developers to ensure smooth operation. Refer to the :doc:`/backends` section to see a list of available backends known to work with the current stable release of NetworkX. .. _introspect: Introspection and Logging ------------------------- Introspection techniques aim to demystify dispatching and backend graph conversion behaviors. The primary way to see what the dispatch machinery is doing is by enabling logging. This can help you verify that the backend you specified is being used. You can enable NetworkX's backend logger to print to ``sys.stderr`` like this:: import logging nxl = logging.getLogger("networkx") nxl.addHandler(logging.StreamHandler()) nxl.setLevel(logging.DEBUG) And you can disable it by running this:: nxl.setLevel(logging.CRITICAL) Refer to :external+python:mod:`logging` to learn more about the logging facilities in Python. By looking at the ``.backends`` attribute, you can get the set of all currently installed backends that implement a particular function. For example:: >>> nx.betweenness_centrality.backends # doctest: +SKIP {'parallel'} The function docstring will also show which installed backends support it along with any backend-specific notes and keyword arguments:: >>> help(nx.betweenness_centrality) # doctest: +SKIP ... Backends -------- parallel : Parallel backend for NetworkX algorithms The parallel computation is implemented by dividing the nodes into chunks and computing betweenness centrality for each chunk concurrently. ... The NetworkX documentation website also includes info about trusted backends of NetworkX in function references. For example, see :func:`~networkx.algorithms.shortest_paths.weighted.all_pairs_bellman_ford_path_length`. Introspection capabilities are currently limited, but we are working to improve them. We plan to make it easier to answer questions such as: - What happened (and why)? - What *will* happen (and why)? - Where was time spent (including conversions)? - What is in the cache and how much memory is it using? Transparency is essential to allow for greater understanding, debug-ability, and customization. After all, NetworkX dispatching is extremely flexible and can support advanced workflows with multiple backends and fine-tuned configuration, but introspection can be helpful by describing *when* and *how* to evolve your workflow to meet your needs. If you have suggestions for how to improve introspection, please `let us know `_! Docs for backend developers ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Creating a custom backend ------------------------- 1. Defining a ``BackendInterface`` object: Note that the ``BackendInterface`` doesn't need to must be a class. It can be an instance of a class, or a module as well. You can define the following methods or functions in your backend's ``BackendInterface`` object.: 1. ``convert_from_nx`` and ``convert_to_nx`` methods or functions are required for backend dispatching to work. The arguments to ``convert_from_nx`` are: - ``G`` : NetworkX Graph - ``edge_attrs`` : dict, optional Dictionary mapping edge attributes to default values if missing in ``G``. If None, then no edge attributes will be converted and default may be 1. - ``node_attrs``: dict, optional Dictionary mapping node attributes to default values if missing in ``G``. If None, then no node attributes will be converted. - ``preserve_edge_attrs`` : bool Whether to preserve all edge attributes. - ``preserve_node_attrs`` : bool Whether to preserve all node attributes. - ``preserve_graph_attrs`` : bool Whether to preserve all graph attributes. - ``preserve_all_attrs`` : bool Whether to preserve all graph, node, and edge attributes. - ``name`` : str The name of the algorithm. - ``graph_name`` : str The name of the graph argument being converted. 2. ``can_run`` (Optional): If your backend only partially implements an algorithm, you can define a ``can_run(name, args, kwargs)`` function in your ``BackendInterface`` object that returns True or False indicating whether the backend can run the algorithm with the given arguments or not. Instead of a boolean you can also return a string message to inform the user why that algorithm can't be run. 3. ``should_run`` (Optional): A backend may also define ``should_run(name, args, kwargs)`` that is similar to ``can_run``, but answers whether the backend *should* be run. ``should_run`` is only run when performing backend graph conversions. Like ``can_run``, it receives the original arguments so it can decide whether it should be run by inspecting the arguments. ``can_run`` runs before ``should_run``, so ``should_run`` may assume ``can_run`` is True. If not implemented by the backend, ``can_run``and ``should_run`` are assumed to always return True if the backend implements the algorithm. 4. ``on_start_tests`` (Optional): A special ``on_start_tests(items)`` function may be defined by the backend. It will be called with the list of NetworkX tests discovered. Each item is a test object that can be marked as xfail if the backend does not support the test using ``item.add_marker(pytest.mark.xfail(reason=...))``. 2. Adding entry points To be discoverable by NetworkX, your package must register an `entry-point `_ ``networkx.backends`` in the package's metadata, with a `key pointing to your dispatch object `_ . For example, if you are using ``setuptools`` to manage your backend package, you can `add the following to your pyproject.toml file `_:: [project.entry-points."networkx.backends"] backend_name = "your_backend_interface_object" You can also add the ``backend_info`` entry-point. It points towards the ``get_info`` function that returns all the backend information, which is then used to build the "Additional Backend Implementation" box at the end of algorithm's documentation page. Note that the `get_info` function shouldn't import your backend package.:: [project.entry-points."networkx.backend_info"] backend_name = "your_get_info_function" The ``get_info`` should return a dictionary with following key-value pairs: - ``backend_name`` : str or None It is the name passed in the ``backend`` kwarg. - ``project`` : str or None The name of your backend project. - ``package`` : str or None The name of your backend package. - ``url`` : str or None This is the url to either your backend's codebase or documentation, and will be displayed as a hyperlink to the ``backend_name``, in the "Additional backend implementations" section. - ``short_summary`` : str or None One line summary of your backend which will be displayed in the "Additional backend implementations" section. - ``default_config`` : dict A dictionary mapping the backend config parameter names to their default values. This is used to automatically initialize the default configs for all the installed backends at the time of networkx's import. .. seealso:: `~networkx.utils.configs.Config` - ``functions`` : dict or None A dictionary mapping function names to a dictionary of information about the function. The information can include the following keys: - ``url`` : str or None The url to ``function``'s source code or documentation. - ``additional_docs`` : str or None A short description or note about the backend function's implementation. - ``additional_parameters`` : dict or None A dictionary mapping additional parameters headers to their short descriptions. For example:: "additional_parameters": { 'param1 : str, function (default = "chunks")' : "...", 'param2 : int' : "...", } If any of these keys are not present, the corresponding information will not be displayed in the "Additional backend implementations" section on NetworkX docs website. Note that your backend's docs would only appear on the official NetworkX docs only if your backend is a trusted backend of NetworkX, and is present in the `.circleci/config.yml` and `.github/workflows/deploy-docs.yml` files in the NetworkX repository. 3. Defining a Backend Graph class The backend must create an object with an attribute ``__networkx_backend__`` that holds a string with the entry point name:: class BackendGraph: __networkx_backend__ = "backend_name" ... A backend graph instance may have a ``G.__networkx_cache__`` dict to enable caching, and care should be taken to clear the cache when appropriate. Testing the Custom backend -------------------------- To test your custom backend, you can run the NetworkX test suite on your backend. This also ensures that the custom backend is compatible with NetworkX's API. The following steps will help you run the tests: 1. Setting Backend Environment Variables: - ``NETWORKX_TEST_BACKEND`` : Setting this to your backend's ``backend_name`` will let NetworkX's dispatch machinery to automatically convert a regular NetworkX ``Graph``, ``DiGraph``, ``MultiGraph``, etc. to their backend equivalents, using ``your_backend_interface_object.convert_from_nx(G, ...)`` function. - ``NETWORKX_FALLBACK_TO_NX`` (default=False) : Setting this variable to `True` will instruct tests to use a NetworkX ``Graph`` for algorithms not implemented by your custom backend. Setting this to `False` will only run the tests for algorithms implemented by your custom backend and tests for other algorithms will ``xfail``. 2. Running Tests: You can invoke NetworkX tests for your custom backend with the following commands:: NETWORKX_TEST_BACKEND= NETWORKX_FALLBACK_TO_NX=True # or False pytest --pyargs networkx How tests are run? ------------------ 1. While dispatching to the backend implementation the ``_convert_and_call`` function is used and while testing the ``_convert_and_call_for_tests`` function is used. Other than testing it also checks for functions that return numpy scalars, and for functions that return graphs it runs the backend implementation and the networkx implementation and then converts the backend graph into a NetworkX graph and then compares them, and returns the networkx graph. This can be regarded as (pragmatic) technical debt. We may replace these checks in the future. 2. Conversions while running tests: - Convert NetworkX graphs using ``.convert_from_nx(G, ...)`` into the backend graph. - Pass the backend graph objects to the backend implementation of the algorithm. - Convert the result back to a form expected by NetworkX tests using ``.convert_to_nx(result, ...)``. - For nx_loopback, the graph is copied using the dispatchable metadata 3. Dispatchable algorithms that are not implemented by the backend will cause a ``pytest.xfail``, when the ``NETWORKX_FALLBACK_TO_NX`` environment variable is set to ``False``, giving some indication that not all tests are running, while avoiding causing an explicit failure. N)partial) entry_points)BackendPrioritiesConfigNetworkXConfig)argmap _dispatchablecg)zKThis does nothing at all, yet it helps turn `_dispatchable` into functions.Nr I/var/www/html/env/lib/python3.13/site-packages/networkx/utils/backends.py _do_nothingrsr F load_and_callc[US9n0nUHunURU;a)[R"SUR3[SS9 M<U(a$UR 5"5X4R'MgXCUR'Mw URSS5 U$![ a5n[R"SURSU3[SS9 SnAMSnAff=f) a; Retrieve NetworkX ``backends`` and ``backend_info`` from the entry points. Parameters ----------- group : str The entry_point to be retrieved. load_and_call : bool, optional If True, load and call the backend. Defaults to False. Returns -------- dict A dictionary mapping backend names to their respective backend objects. Notes ------ If a backend is defined more than once, a warning is issued. The `nx_loopback` backend is removed if it exists, as it is only available during testing. A warning is displayed if an error occurs while loading a backend. )groupz)networkx backend defined more than once: ) stacklevelz0Error encountered when loading info for backend z: N nx_loopback)rnamewarningswarnRuntimeWarningload Exceptionpop)rritemsrvepexcs r _get_backendsr"s, u %E B 77b= MM;BGG9E    ggik77 rwwK#$FF=$ I  FrwwirRUQVW"  s!B C%*CCznetworkx.backendscUR5RS5Vs/sHoR5=n(dMUPM sn$s snf)N,)stripsplit)stringxstrippeds r_comma_sep_to_listr*&s;$lln2237 S7 0_set_configs_from_environment..4s%J'" %J)algos generatorsdefault_configNETWORKX_CACHE_CONVERTED_GRAPHSNETWORKX_FALLBACK_TO_NXFNETWORKX_WARNINGS_TO_IGNOREr$)backend_prioritybackendscache_converted_graphsfallback_to_nxwarnings_to_ignorenetworkxz2All installed NetworkX backends and their configs.NETWORKX_BACKEND_PRIORITY_Nr3NETWORKX_BACKEND_PRIORITYNETWORKX_AUTOMATIC_BACKENDSr4r ) backend_infoupdater"r;keysrrrr isinstanceboolosenvirongetr&r%type__doc__ startswithlowerr:r*rr3r4sorted) r/infocfgr(configkeyval prioritiesr:s r_set_configs_from_environmentrW*s~ &=TRS%-]]_|7H7H7J%J *   &2%7%7%9 &:MG $t+".>)?"?#HH#X &:    $ JJNN>6 7 BC#* .. j  :>>'23  JJNN+ DK#LLN  +DA bEMDc)$$((#27>33;%%))1R.#9@S  + DK ".!3!3!5 !5 d" '+tK/@'@ !5  ) )A$H k"4('+t$ C" s4A2S1 S7S7)S7cTUR=nbU$UR5=olU$)zIf the cached documentation exists, it is returned. Otherwise, the documentation is generated using _make_doc() method, cached, and then returned.)r _make_doc)rmrs rrM_dispatchable.__doc__s1 "" "B /I $ 00  r cXlSUlg)zWSets the original documentation to the given value and resets the cached documentation.N)rr)rmrUs rrMrs r c URGc9[R"UR5n[ SUR R 555(dUR/UR R 5Q[R"S[RRSS9P[R"S[RR5PS9nO]UR R 5Gtp#UR/UQ[R"S[RRSS9PUPS9nXlUR$)zrReturn the signature of the original function, with the addition of the `backend` and `backend_kwargs` parameters.Nc3n# UH+oR[RR:Hv M- g7fr-)kindinspect Parameter VAR_KEYWORD)r.ps rr0._dispatchable.__signature__..s'AXA'++777AXs35r/)defaultbackend_kwargs parameters) rr signatureranyrvaluesreplacer KEYWORD_ONLYr)rmsigr var_keywords r __signature___dispatchable.__signature__s> 99 ##DNN3CADAVAVAXkk ..0 ))%w'8'8'E'Et   )),g.?.?.K.K  " ,/>>+@+@+B(kk # ))%w'8'8'E'Et  $  "Iyyr )r/c>[(d*UbUS:wa[SUS35eUR"U0UD6$UnUbU[;a[SUS35e0nURR 5HupgU[ U5:a%Xc;a[URSU<35eX'nO5Xc;aX6nO+X`R;a[URSU35eMnUc-X`R;a[URSU<S35eMXU'M UR(a[U5nURUR5-H0n[XV5n XU'Xc;aXU'MXURU'M2 UR 5VV s1sH#upjX`R;dM[U S S5iM% n nn URUR5-HnU RS XV55 M O+UR5V s1sHn [U S S5iM n n [ R"R$R'URUR((a$[ R"R$R*O#[ R"R$R,5n UR.(a7U (a0Uc-UR1U S UU[ R"R2S 9$U R5S5 UGbS US3n SUSURSU 3nU (aX1:XacUR7XBU5(aUR9XBX>S9$UR;U5(aSnOSn[=SURSUSUSU 35eUR?XK5(aUR7XBU5(awURAX#5(a$[BRESURU5 /nOSnURGUU UUUUS9nU(aUHunnURIUS5 M U$UR;U5(aSnOSn[=SURSUSUSU 35e[ U 5S:XaSnS[K[MU 55S3n OSn[SURSUSU SUSUS U 3 5eURAX#5(GaS!n S"n[ U 5S:XaU unS#US$URS%U 3nUR7XBU5(aUR9UUUUS&-S9$[ R"R2(aH[OS'UR555(a#[BRES(UURU5 OUR;U5(aS&nOSn[=UU-5e[ R"R2(aH[OS+UR555(a#[BRES,URU U5 O[QSURS-U S.U 35eUR"U0UD6$[ R"R2(dU (dS/nO/n[S5n/n/nU HFnUU;aM URUU5 UU ;aURWU5 M5URWU5 MH /n/nUHFnUU;aM URUU5 UU ;aURWU5 M5URWU5 MH U U- n[ U5S:a#[BRES/URU5 S0n[[XRZ"UUUUU55n [ U 5S:a+[BRES1URU =(d S2U 5 /n![]U 5GHun"nU"(a[BRES3U5 U (aX1:Xa-UR7XBU5(aUR9XBU5s $M_UR?XK5(aUR7XBU5(aUR_XBU5(aVURGXKX#5nUR((a/U (a(XK;a#[BRES4URU UU5 Us $U!RWU5 GM GMGM U!Hnn[BRES6U5 URGXKX#5nUR((a/U (a(XK;a#[BRES4URU UU5 Us $ [ U U- =n#5S:a"[S7U S8URS9U S:U#S;3 5e[=SURSzReturns the result of the original function, or the backend function if the backend is specified and that backend implements `func`.Nr?r]r^z() got multiple values for z$() missing required graph argument: z() required graph argument z is None; must be a graph__networkx_backend__c3<# UHn[USS5v M g7frN)getattrr.gs rr0)_dispatchable.__call__..s$+3A5t<<3rr=zZNo other backends will be attempted, because the backend was specified with the `backend='z'` keyword argument.z3' backend raised NotImplementedError when calling `z'.  extra_messagez for the given argumentsr9`z' is not implemented by 'z ' backendz. z`%s' will mutate an input graph. This prevents automatic conversion to, and use of, backends listed in `nx.config.backend_priority`. Using backend specified by the `backend='%s'` keyword argument. This may change behavior by not mutating inputs.r mutationsrsz)' is unable to convert graph from backend z to 'z2' backend, which was specified with the `backend='z'` keyword argument. zconversions between backends (if configured) will not be attempted, because this may change behavior. You may specify a backend to use by passing e.g. `backend='networkx'` keyword, but this may also change behavior by not mutating inputs.)zThis call will mutate inputs, so fall back to 'networkx' backend (without converting) since all input graphs are instances of nx.Graph and are hopefully compatible.z Backend 'z' does not implement `z2'%s. This call will mutate an input, so automatic z with these argumentsc3V# UHn[U[R5v M! g7fr-rGrlGraphrs rr0rs'8":A#1bhh//!9')zBackend '%s' can't run `%s'. %sc3V# UHn[U[R5v M! g7fr-rrs rr0rs U>4262 2   # L(H,/IJK K++++-JESY?#tyyk1LUI$VWW  222yyk!EeWM} 4 44#99+%@ Ibc5 */&'.:   :D))O,@,@,BB!%o&"II;c%* '*=*O((VDD22$F3**<886EE) {";L>gRw(  CC((VDD33DAA / !II(%' $( //$+&3"+ 0B!*3JE3"IIc40 +4 I**<886EE) {";L>gRw(&'1,()$t4G/H*I)J!&L#DII;GyPQ&'u\N;00<~=R'   ' ' 5 5:  N &'1,!4 ~-CDII;ODDI7L &H,,\HH#66( "*69P*P 7 I&yy//C8"1!7!7!9 855 =( II*  22<@@$;E$&E1,2FGG))c2)//1 2// PII'" # {#//B.C>4262 2 99 # #+>!+| ! xu$Dt| HHTN** d# d#%$Dt| HHTN** d# d#%%t+ v;?" MM8   FPQ y>A  MM6 #+t  !#*3I*> &L, 9<H) *.A^.S,,\HH#66|6RRI&& ++LGG// FKK!33(t!// 3 , G$MM!X!% 3 , , " )00>9H+?`2L MMDl  ++ t''+$?MMP +$$ -2D ':T'AA# BQ F01D0EF {#[!!!5 67UU " {29+>/ /  O ##T+ UO# UHrupURS5(a.[T5U:aTUOTRUSSS5(+O&[T5U:aTUOTRU5SLv Mt g7f)znot NT)rNrrK)r.arg_namearg_posrYrZs rr08_dispatchable._will_call_mutate_input..s *?%H&&v.. 4y7*M HQRL$7 (+4y7':d7m 8@T*?sA:A=)rrr)rmrYrZrs `` rr%_dispatchable._will_call_mutate_inputsH!%!3!33  T !  *7)<)<)>   r cUS:H=(d URSU15nU(d[RSUU5 U$)Nr?z2Unable to convert from %s backends to '%s' backend)issubsetrr)rmrdrrs rr_dispatchable._can_convertsJZ ' +>+G+G  &,  MMD#   r cPUS:Xag[U5n[X R5$)z/Does the specified backend have this algorithm?r?T)rercr)rmrdr/s rr _dispatchable._does_backend_haves& : % -w **r c US:Xag[U5n[X@R5(d![R SXR5 gUR URX#5n[ U[5(dU(dJ[ U[5(aSU3OSn[R SUUR[XU5U5 gg)zBCan the specified backend run this algorithm with these arguments?r?Tz$Backend '%s' does not implement `%s'F , because: r9z0Backend '%s' can't run `%s` with arguments: %s%s) rercrrrr_rGr _LazyArgsRepr)rmrdrYrZr/r_reasons rr_dispatchable._can_backend_runs : % -w ** MM6 ii //$))T: gs # #70:7C0H0H{7),bF MMB d&1  r c ,US:Xag[U5nURURX#5n[U[5(dU(dJ[U[5(aSU3OSn[ R SUUR[XU5U5 gg)zzShould the specified backend run this algorithm with these arguments? Note that this does not check ``backend.can_run``. r?Trr9z4Backend '%s' shouldn't run `%s` with arguments: %s%sF)rer`rrGrrrr)rmrdrYrZr/r`rs rr!_dispatchable._should_backend_runs : % -'' 4@ j# & &j3=j#3N3N{:,/TVF MMF d&1  r c URR"U0UD6nUR5 UR(dURnUS UR U4$US:XaS=n=pO:s++5j$//'5 ',#! ',#     C ( (!}#38//*QrBR2S2SYqL2S %//*566&*#! ,8#ooj91= ..7('44 38//'2J2P2P2PYqL2P " !+ 0 0 2 2HC!&!55IX *S#:N:N5??..sA6TWW 2  % '  D (J +S 1 123t;x 34@@ '+#! !45>:s++5j$//'5 ',#! ',#     C ( (!}#6;__ZPQRTEU5V5V ItO5V %//*566&*#! ,8#ooj94@ " !+ 0 0 2 2HC!&!55IU z#s7K7K5??..s3QTT 2 [[E((( #__U3*4q"8*EU''$#-#-,?,?-A#("+"+(  4*&$.= 4 44 #;E7% {R[\1488%*N/33E:FE%8N&E1488%*N/33E:FE%8N&E2C88%*.B%BN%9N5"8*EU-1-@-@$#(#(,:,:-;#("+"+.A .EOOE*Y!p||  #zz<''iV *s0> V= WW8W1 W W77W"5Wc XU (a[USS5=n bU RS05RU05n [UUUUUS9n [XU S9upUbvS[R R ;a([R"SU<SURS35 [RS [US S5UURU5 U$US :Xa\[US 5(d$[RS URUU5 U$[UR5nURU5nO4[U5nUR!UUUUUU=(d U URUS 9nU (aAW b>U c;[#W W U5 [RS[US S5UURU5 U$)N__networkx_cache__r;r{r|r}r~r)rrzNote: conversions to backend graphs are saved to cache (`G.__networkx_cache__` on the original graph) by default. This warning means the cached graph is being used for the z backend in the call to a. For the cache to be consistent (i.e., correct), the input graph must not have been manually mutated since the cached graph was created. Examples of manually mutating the graph data structures resulting in an inconsistent cache include: >>> G[u][v][key] = val and >>> for u, v, d in G.edges(data=True): ... d[key] = val Using methods such as `G.add_edge(u, v, weight=val)` will correctly clear the cache to keep it consistent. You may also use `G.__networkx_cache__.clear()` to manually clear the cache, or set `G.__networkx_cache__` to None to disable caching for G. Enable or disable caching globally via `nx.config.cache_converted_graphs` config. To disable this warning: >>> nx.config.warnings_to_ignore.add("cache") zZUsing cached converted graph (from '%s' to '%s' backend) in call to `%s' for '%s' argumentrr?zUnable to convert input to 'networkx' backend in call to `%s' for '%s argument, because it is not from a backend (i.e., it does not have `G.__networkx_backend__` attribute). Using the original object: %s)r{r|r}r~rrrzUCaching converted graph (from '%s' to '%s' backend) in call to `%s' for '%s' argument)r setdefault_get_cache_key_get_from_cacherlrSr>rrrrrrcrer convert_to_nxconvert_from_nx _set_to_cache)rmrdrr{r|r}r~rrrrnx_cacherrT compat_keyrr/s rr"_dispatchable._convert_graphs $U,@$GGT'' B7BB">>MM#$0"23##'99+.N N. 8E#94@ II  : %5"899 !II #E$>$>?G&&u-B#L1G((%%$7$7&:%FYYY%) B -)2C %b ) MM45t<    r rc `US:XaUR"U0UD6$[U5n[RSUUR[ XU55 [ XPR5"U0UD6$![a7nUb.[RSUURU5 [U5UeeSnAff=f)zICall this dispatchable function with a backend without converting inputs.r?6Using backend '%s' for call to `%s' with arguments: %sNr)rrerrrrrr)rmrdrYrZrr/r!s rr _dispatchable._call_with_backend?s : %>>4262 2 - D  II $f -  7II.?? ?" ( ? II  *-8cA  sA,, B-62B((B-rc *US:Xa URnO [U5n[XR5nX!1- n [R S[ U 5S:aU OS[[U 55S3[ U 5S:aSOSUUR5 URUUU[RRUS9upUS:wa,[R S UUR[X U 55 U"U 0U D6$![aGn [R "SUcSOS -UUUR/UcS OU 4Q76 Ub [U5U eeS n A ff=f![a7n Ub.[R S UURU 5 [U5U eeS n A ff=f)aCall this dispatchable function with a backend after converting inputs. Parameters ---------- backend_name : str input_backend_names : set[str] args : arguments tuple kwargs : keywords dict extra_message : str, optional Additional message to log if NotImplementedError is raised by backend. mutations : list, optional Used to clear objects gotten from cache if inputs will be mutated. r?zJConverting input graphs from %s backend%s to '%s' backend for call to `%s'rr]rr9rrzAFailed to convert graphs from %s to '%s' backend for call to `%s'Nz: %sr r;r)rrerrrrrrrr,rlrSr<rr) rmrdinput_backend_namesrYrZrrrr/other_backend_namesconverted_argsconverted_kwargsr!s rr_dispatchable._convert_and_callWs. : %>>D#L1G7II.D1NB X&'!+ T$2345Q7*+a/CR  II  /3/F/F))::# 0G0 ,N* : % MMH d4DE   <+;< <-#  MMS&.2F<#   &-"C6  ()-8cA  .# ( ? II  *-8cA  s1-C=5E= EAE  E F2F  Frcf^^^^^^ ^!^"^#^$^%^&^'^(^)^*^+^,[U5nTRXU5(dU(dTR(dEU(a,[R SUTR [ TX#55 TR"U0UD6$SSKnSTR SU3n[UTR 5(aUS- nURU5 SSK J mJ m Jm! SSKJm'Jm( SS KJmJmJm$Jm% SS KJm+ SS KJm" SSKm)SS KJmJm# SS KJm* U(dU=pO[AUUUU U"U#U$U%U'U(U+4 SjU56upU(dU=pOC[AUUUU U"U#U$U%U'U(U+U,4 SjURC556up[EU 5n [EU 5n TRGXU SSS9up[R SUTR [ TX55 [IUTR 5"U 0U D6nTRR[UW[VRX5=(dC [US5=(d0 [UU[Z[\-5=(a [_SU55:wavTR S;a[_SU55(dOTR S;a[_SU55(d(TR S;a[aSTR 35eS5UU U!U&U)UU*4Sjjm&U&U4SjnTR S;aO+[UUT 5(a U"U5nOT&"U5 T&"U5 TR S#;Ga\TRbRd"W 0W D6nURg5 TRbRd"U 0U D6nURg5 TR S$;a|URiURjS%5nURjS%nURlUl6URo5(aURpUl8[VRr"U5 GOgTR S&:XaURiURjS'5nURjS'nUbwUbtURtRC5HunnUS(URtUS('M URvRyURv5 [VRr"U5 GOTR S):XaURjS*bURiURjS%5nURjS%nURjS*nURzRC5HunnUUURzUU'M [VRr"U5 GOTR S+;a~URjS,(djURiURjS%5nURjS%nUR|RyUR|5 [VRr"U5 GOsTR S-:XaURjS,(d~URiURjS%5nURjS%nURtRC5HunnUS.URtUS.'M [VRr"U5 GOTR S/:XaURjS,(aTR S0;GaURiURjS%5nURjS%nUULaU$UR~R5 UR~RyUR~5 URlR5 URlRyURl5 [US15(aP[US15(a?URpR5 URpRyURp5 [US25(aP[US25(a?URR5 URRyUR5 [VRr"U5 TR S/:XaU$URiU5$URiU5n[UU[VRX5(Ga TR S3;aTR"U 0U D6nRRUU5(dUR5UR5:XdeUR5UR5:XdeURvURv:XdeURzURz:XdeURUR:Xde[OU5[OU5Lde[S45eU$U$![JanU(a8[R SUTR 5 TR"U 0U D6sSnA$SSKnURURL(aURLSO#TR S[OU5RP35 SnAGNSnAff=f![`a-n[aTR S US![OU5S"35UeSnAff=f)6zECall this dispatchable function with a backend; for use with testing.zZFalling back to use 'networkx' instead of '%s' backend for call to `%s' with arguments: %srNr]z' not implemented by z with the given arguments)IterableIteratorMapping)copydeepcopy)BufferedReaderBytesIOStringIO TextIOWrapper)tee)Random) Generator RandomState)sparrayc3> # UHtn[UT5(a UT "U54OS[UTT-T-T-5(a UT "U54O/[UT5(a[UTT -5(dT "U5OX4v Mv g7fr-rG) r.argrJrKrPrFrOrQrLrMrHrIrNs rr0<_dispatchable._convert_and_call_for_tests..s  $"#{33(3-("#w'9F'BY'NOOtCy)"#x00&sN],JKKS$ $sA # UHup[UT5(a X4UT "U544Og[UTT -T-T-5(a X4UT "U544O@[UT5(a*[UTT -5(dUT "U5=mS4UTS44OX4X44v M g7f)rrNrT)r.rrrJrKrPrFrOrQrLrMrHrIrNteeds rr0rVs !/"![11Va!-."!Wx%7&%@9%LMM&1d1g,/"!X..&q.=*HIIs1v~tq12QQLA&1&)*!/sBBFr>r;z`Graph conversion failed; falling back to use 'networkx' instead of '%s' backend for call to `%s'z raised rc3|# UH2n[U[R5=(d [US5v M4 g7fr)rGrlrrcr.r(s rr0rVs2#q"((+Qwq:P/QQ#s:<>check_planaritycheck_planarity_recursivec3(# UHoSLv M g7fr-r rZs rr0rVs26aT 6r2>held_karp_ascentc3B# UHn[U[5v M g7fr-)rGrrZs rr0rVs all_triadsnonisomorphic_treesgeneral_k_edge_subgraphsz!`returns_graph` is incorrect for c `>[UTR5(a*[TRSUS[ U5SUS35e[UTR T -5(ag[U[ R5(a)T"URUS-S9 T"URUS-S9 g[UT5(a[e[UT5(a'[U[5(dUH nT"X!S-S9 M [UT5(a!UR5H nT"X!S-S9 M gg)N returned a numpy scalar  (z, depth=)r)depth) rGnumberrrrLndarrayrlr_node_adjrrr) rUrgr(rErFrG check_resultnprmrRs rrl?_dispatchable._convert_and_call_for_tests..check_result*s #ryy))"yyk!:3%r$s)HUZT[[\]#rzzG344#rxx((SYYeai8SXXUQY7#x(())#x((C1E1EA !)4#w''A !)4&(r c 3># UHnT"U5 Uv M g![a-n[TRSUS[U5S35UeSnAff=f7f)Nrdrerf)rrrL)itrUr!rlrms rcheck_iteratorA_dispatchable._convert_and_call_for_tests..check_iterator>se %  $&99+%>se2d3i[PQRs$A A A(A  AA> from_edgelistrdrerf> barycenter edmonds_karp relabel_nodescontracted_edgecontracted_nodesstochastic_graphmaximum_branchingminimal_branchingrecursive_simple_cyclesconnected_double_edge_swapminimum_spanning_arborescence incremental_closeness_centrality>r{r|r}r~rxruresidualflowrtattr>rwrxrHryweightrv>r_pred_succ>read_gml read_gexf from_pydot read_pajek read_graph6 preflow_push read_adjlist read_graphml read_sparse6 read_edgelistpydot_read_dotquotient_graphagraph_read_dotboykov_kolmogorovspectral_graph_forgeread_multiline_adjlistbipartite_read_edgelistshortest_augmenting_pathzGraphs are not equal)r)Hrerrzrrrrrpytestrcxfailcollections.abcrErFrGrHrIiorJrKrLrMrrNrandomrOnumpy numpy.randomrPrQ scipy.sparserRziprrr,rrrYrLrrrrGrlrtuplerrrrrrr4r rk is_directedr _clear_cacher(rrEr*rrjclearrutils graphs_equalnumber_of_nodesnumber_of_edgesadjAssertionError)-rmrdrYrZr=r/rmsgargs1args2kwargs1kwargs2rArBresultr!rqr#bound2G1G2R1R2rrrconverted_resultrxrJrKrPrErFrGrOrQrLrMrlrHrIrmrRrNrXs-` @@@@@@@@@@@@@@@@@rr)_dispatchable._convert_and_call_for_testss -$$\@@T[[!MM>$ %dD9 ~~t6v66 dii[ 5l^DCw **22 LL ??'GG!!7(  EE   $  LE & &Gg"  !'    G7mG7mG /3/F/FW0G0 ,N MMH dNE   Wdii0.UDTUF&   6288,6#9:fedl3#  MM26222 11>##!xxBH#n,**5??:+FG%%j1>bn " 01./i F+!1HHOOBHH-OOB'l*uv/F/R**5??3+?@%%c*v.HHNN,DAq()$BHHQK%-# DD/**5??3+?@%%c* ""2;;/#009P**5??3+?@%%c*HHNN,DAq,-hKBHHQK)-# _,/99 DD**5??3+?@%%c*8I ) rww'2w''GB,@,@HHNN$HHOOBHH-2w''GB,@,@HHNN$HHOOBHH-#99/I((0 0"008 & 1 1diiH 7 411A88((,<==((*.>.N.N.PPPP((*.>.N.N.PPPPww"2"8"8888ww"2"8"8888uu 0 4 4444Aw$'7"8888$%;<<Ho#  7 II  ~~u888  LL"xx  {(49CUCUBV-W   n  "yyk!:6("T&\NRST s> Ag i9 i69i1i6Ai11i69 j0(j++j0cUR(d UR$SS/n[UR5GHn[UnSU;aUR USUS35 OUR U5 SU;dUR US;aUR S5 MjUSUR nUR S5=(d UR S5=n(a*URS URS 555 S nOS nUR S 5=(d UR S5=n(aU(aUR S5 UR S5 [U5HGnUR SU35 Xx=n (aUR SU 35 UR S5 MI OUR S5 UR S5=n (dGMUR SU S35 UR S5 GM UR5 SRU5n UR(dSUR SU 3$URR5SU 3$)zGenerate the backends section at the end for functions having an alternate backend implementation(s) using the `backend_info` entry-point.Backendsz-------- short_summaryz : rr9additional_docsextra_docstringc3<# UHo(aSU3OUv M g7f)z Nr )r.lines rr0*_dispatchable._make_doc..s!>Sd4bKT1>Sr TFextra_parametersadditional_parametersz Additional parameters:z z urlz [`Source `_]z zThe original docstring for z was empty. z ) r;rrPrDrrrKextendr&rjoinrstrip) rmlinesr/rQ func_info func_docsadd_gaprparamdescfunc_urlto_adds rr_dispatchable._make_docs?}}>> !   dmm,G(D$& yD,A+BCD W%$&$))4 ;L*L R [)$))4I /0TIMMBS4Ty >Good>S 01:==!89LL$ 78#$45ELL4w0/66t6 vdV_5LL$ 6  R $==//x// z(489 R S-V  u%~~0 ;NvhW W..'')*(6(;;r c([UR44$)zxAllow this object to be serialized with pickle. This uses the global registry `_registered_algorithms` to deserialize. )_restore_dispatchabler)rms r __reduce___dispatchable.__reduce__ s %tyyl22r )rrrsrrrtrrrrrr;r{rzrrrr|rrr}rr~r-)rrrsrtrurrwrpropertyrMsetterrrrrrrrr,r"rrrrrrvr r rr r sK , ,&'Os!!" sj ^^  ""H*.g R & +2.Q(fiVOS>Nb=Bi V 9 !t 4 $( #6 LT%5 DDLT!TU](:K:KD:Q:Q5 DDLT!TU](:K:KD:Q:Q$  %!67<& &$7 r )rdcUb"URS05RU05n0nUupVX U'[U5HnXq:XaM UupUSLdUSLaO"USLdUSLdURU5(dM;U SLdUSLaO"U SLdUSLdU RU5(dMhURUS5=ncMX$U'M U$)a:Set a backend graph to the cache, and remove unnecessary cached items. Parameters ---------- cache : dict If ``backend_name`` is given, then this is treated as ``G.__networkx_cache__``, but if ``backend_name`` is None, then this is treated as the resolved inner cache such as ``G.__networkx_cache__["backends"][backend_name]``. key : tuple Cache key from ``_get_cache_key``. graph : graph backend_name : str, optional Name of the backend to control how ``cache`` is interpreted. Returns ------- dict The items that were removed from the cache. Nr;FT)r1rr r) rrTrrdremovedrrcur_keyrrs rr6r6r s(  R0;;L"M GH#J; >   5=H,  T\X.dmmH6M6M  5=H,  T\X.dmmH6M6M YYw- -E :$G  Nr c$\rSrSrSrSrSrSrg)ri zOSimple wrapper to display arguments of dispatchable functions in logging calls.c6XlX lX0lSUlgr-)rrYrZvalue)rmrrYrZs r__init___LazyArgsRepr.__init__ s    r cURcuURRR"UR0UR D6nSR SURR555nSUS3UlUR$)Nz, c36# UHupUSU<3v M g7f)=Nr )r.rTrUs rr0)_LazyArgsRepr.__repr__.. sW?V83Qsg.?Vs(rf) rrr bind_partialrYrZrr r)rmr#inners r__repr___LazyArgsRepr.__repr__ sm :: II++88$))St{{SEIIWu?T?T?VWWEUG1DJzzr )rYrrZrN)rrrsrtrurMrrrvr r rrr sY r r_NETWORKX_BUILDING_DOCS_c fUc[[40UD6$[U40UD6nURUlU$r-)rr _orig_dispatchablerM)rrZdispatched_funcs rr r s8 <=3F3 3,TrsbSj +>>     H %V+0+b , - TBJ R3R3j44.15?D6:,^"::>>,-- '/66>>M   /77 8D"&,,"&//"7"7"9H"9$!Q%ZA"9H#/#M#.$Is  E /E