ph|(SrSSKrSSKJr SSKJr SSKrSSK J r J r J r J r JrJrJrJr SSKJrJrJrJrJrJrJrJrJrJrJr SSKJr SS K J!r! \RD"\#5r$S r"S S 5r%SS jr&\ RN4Sjr(Sr)\ RN4Sjr*Sr+\ RN4Sjr,"SS\ RZR\5r/Sr0\ RN4Sjr1\ RN4Sjr2Sr3S Sjr4S Sjr5S Sjr6Sr7S!Sjr8S!Sjr9g)"a^ Methods for computing actual causation of subsystems and mechanisms. If you use this module, please cite the following papers: Albantakis L, Marshall W, Hoel E, Tononi G (2019). What Caused What? A quantitative Account of Actual Causation Using Dynamical Causal Networks. *Entropy*, 21 (5), pp. 459. ``_ Mayner WGP, Marshall W, Albantakis L, Findlay G, Marchman R, Tononi G. (2018). PyPhi: A toolbox for integrated information theory. *PLOS Computational Biology* 14(7): e1006343. ``_ N)chain)log2) Directioncomputeconfig connectivity constants exceptionsutilsvalidate) Account"AcRepertoireIrreducibilityAnalysisAcSystemIrreducibilityAnalysis ActualCut CausalLinkDirectedAccountEventNullCut _null_ac_ria _null_ac_siafmt)mip_partitions) SubsystemcH[[U5[R5$)zRounded version of ``log2``.)round_log2r PRECISION)xs F/home/james-whalen/.local/lib/python3.13/site-packages/pyphi/actual.pyrr(s q6++ ,,c\rSrSrSrS&SjrSrSrSrSr S r S r \ S 5r S rS rSrSrSrSrSrSrSrSrSrSrSrSrSrSrSrSrSr S'Sjr!S'S jr"S(S!jr#S'S"jr$S'S#jr%S$r&S%r'g)) Transition-aA state transition between two sets of nodes in a network. A |Transition| is implemented with two |Subsystem| objects: one representing the system at time |t-1| used to compute effect coefficients, and another representing the system at time |t| which is used to compute cause coefficients. These subsystems are accessed with the ``effect_system`` and ``cause_system`` attributes, and are mapped to the causal directions via the ``system`` attribute. Args: network (Network): The network the subsystem belongs to. before_state (tuple[int]): The state of the network at time |t-1|. after_state (tuple[int]): The state of the network at time |t|. cause_indices (tuple[int] or tuple[str]): Indices of nodes in the cause system. (TODO: clarify) effect_indices (tuple[int] or tuple[str]): Indices of nodes in the effect system. (TODO: clarify) Keyword Args: noise_background (bool): If ``True``, background conditions are noised instead of frozen. Attributes: node_indices (tuple[int]): The indices of the nodes in the system. network (Network): The network the system belongs to. before_state (tuple[int]): The state of the network at time |t-1|. after_state (tuple[int]): The state of the network at time |t|. effect_system (Subsystem): The system in ``before_state`` used to compute effect repertoires and coefficients. cause_system (Subsystem): The system in ``after_state`` used to compute cause repertoires and coefficients. cause_system (Subsystem): system (dict): A dictionary mapping causal directions to the system used to compute repertoires in that direction. cut (ActualCut): The cut that has been applied to this transition. .. note:: During initialization, both the cause and effect systems are conditioned on ``before_state`` as the background state. After conditioning the ``effect_system`` is then properly reset to ``after_state``. Nc XlX lX0lURRnU"U5UlU"U5UlU"XE-5UlUbUO[URUR5Ul U(aSn O3[[[UR5[U5- 55n [R"SS9 [XURURU S9Ul[XURURU S9UlSSS5 X0R"lUR"R&Hn X:R(U lM [*R,"UR"5 [.R0UR"[.R2UR 0Ulg!,(df  N=f)NF)VALIDATE_SUBSYSTEM_STATES)_external_indices)network before_state after_state node_labelscoerce_to_indices cause_indiceseffect_indices node_indicesrcuttuplesortedsetroverrider effect_system cause_systemstatenodesindexr state_reachablerCAUSEEFFECTsystem) selfr)r*r+r.r/r1noise_backgroundr-external_indicesnodes r __init__Transition.__init__[s (& ,,>>.}=/?-m.LM?C !2!2D4D4DE   "  %VG(()C ,>>&@ A  __u =!*7+/+<+#.%%++D$ZZ0DJ,   !2!23 OOT..   d00  )> =s A F<< G c.[R"U5$N)rfmt_transitionr?s r __repr__Transition.__repr__s!!$''r!c[U5$rF)reprrHs r __str__Transition.__str__s Dzr!ctURUR:H=(a URUR:H=(ay URUR:H=(aY URUR:H=(a9 URUR:H=(a UR UR :H$rF)r.r/r*r+r)r1)r?others r __eq__Transition.__eq__s   %"5"5 5 "   5#7#7 7 "   !3!3 3 "    1 1 1 " LLEMM )  " HH !  r!c[URURURURUR UR 45$rF)hashr.r/r*r+r)r1rHs r __hash__Transition.__hash__sBT'')<)<&&(8(8$,,XX  r!c,[UR5$rF)lenr0rHs r __len__Transition.__len__s4$$%%r!c[U5S:$)Nr)rXrHs r __bool__Transition.__bool__s4y1}r!c.URR$rF)r)r,rHs r r,Transition.node_labelss||'''r!cURURURURURUR S.$)z*Return a JSON-serializable representation.r)r*r+r.r/r1rarHs r to_jsonTransition.to_jsons@|| --++!//"1188   r!c[URURURURUR U5$)z(Return a cut version of this transition.)r#r)r*r+r.r/)r?r1s r apply_cutTransition.apply_cuts:$,,(9(94;K;K,,d.A.A3H Hr!cBUR[RX5$)zReturn the cause repertoire.) repertoirerr<r? mechanismpurviews r cause_repertoireTransition.cause_repertoiresy CCr!cBUR[RX5$)zReturn the effect repertoire.)rhrr=ris r effect_repertoireTransition.effect_repertoiresy//DDr!c&URSU5$)z;Return the unconstrained cause repertoire of the occurence.r&)rlr?rks r unconstrained_cause_repertoire)Transition.unconstrained_cause_repertoires$$R11r!c&URSU5$)zr,r4issubsetpurview_indices ValueErrorformatr fmt_mechanismmechanism_indicesrh)r? directionrjrkr>r,s r rhTransition.repertoiresY'(( 7|$$T%9%9)%DEE;BB!!'7JK K9~&&t'='=i'HII<CC!!)99LM M  w??r!cj^URU5n[U4Sj[U555nX%$)a6Compute the probability of the purview in its current state given the repertoire. Collapses the dimensions of the repertoire that correspond to the purview nodes onto their state. All other dimension are already singular and thus receive 0 as the conditioning index. Returns: float: A single probabilty. c3<># UHupUT;aUOSv M g7f)rNr&).0rB node_staterks r /Transition.state_probability..s'H.F*$%)GOj:.F) purview_stater2 enumerate)r?rrhrkrr:s ` r state_probabilityTransition.state_probabilitys=**95 H.7 .FHH  r!cJURXU5nURXU5$)zXProbability that the purview is in it's current state given the state of the mechanism. )rhr)r?rrjrkrhs r probabilityTransition.probabilitys'__Y7C %%iWEEr!c(URUSU5$)z)Unconstrained probability of the purview.r&)r)r?rrks r unconstrained_probability$Transition.unconstrained_probabilitys 2w77r!ct[RUR[RUR0U$)zThe state of the purview when we are computing coefficients in ``direction``. For example, if we are computing the cause coefficient of a mechanism in ``after_state``, the direction is``CAUSE`` and the ``purview_state`` is ``before_state``. )rr<r*r=r+r?rs r rTransition.purview_states8 OOT..   d..   r!c4URUR$)zIThe state of the mechanism when computing coefficients in ``direction``. )r>r8rs r mechanism_stateTransition.mechanism_states{{9%+++r!ct[RUR[RUR0U$)z-The indices of nodes in the mechanism system.)rr<r/r=r.rs r r~Transition.mechanism_indicess8 OOT00   d00   r!ct[RUR[RUR0U$)z+The indices of nodes in the purview system.)rr<r.r=r/rs r rzTransition.purview_indicess8 OOT//   d11   r!c\[URXU5URX5- 5$rF)rrr)r?rrjrks r _ratioTransition._ratio$s4D$$Y7C229FGH Hr!cBUR[RX5$)z7The cause ratio of the ``purview`` given ``mechanism``.)rrr<ris r cause_ratioTransition.cause_ratio(s{{9??I??r!cBUR[RX5$)z8The effect ratio of the ``purview`` given ``mechanism``.)rrr=ris r effect_ratioTransition.effect_ratio,s{{9++Y@@r!cBURUnURX5$)zACompute the repertoire over the partition in the given direction.)r>partitioned_repertoire)r?r partitionr>s r r!Transition.partitioned_repertoire0s!Y',,YBBr!c\URX5nURXUR5$)zLCompute the probability of the mechanism over the purview in the partition. )rrrk)r?rrrhs r partitioned_probability"Transition.partitioned_probability5s-00F %%iY=N=NOOr!c [S5nURXU5n[X#UR5HnUR X5n[ Xh- 5n [ R"U S5(d U S:a3U(d,[URU5UUUUUUURSS9 s $[U5[U 5- [R:dMU n[URU5UUUUUUURUS9 n M W $)aFind the ratio minimum information partition for a mechanism over a purview. Args: direction (str): |CAUSE| or |EFFECT| mechanism (tuple[int]): A mechanism. purview (tuple[int]): A purview. Keyword Args: allow_neg (boolean): If true, ``alpha`` is allowed to be negative. Otherwise, negative values of ``alpha`` will be treated as if they were 0. Returns: AcRepertoireIrreducibilityAnalysis: The irreducibility analysis for the mechanism. infrg) r8rrjrkrrrr,alpha) floatrrr,rrr eqrrabsr EPSILON) r?rrjrk allow_neg alpha_minrrrracrias r find_mipTransition.find_mip@s $%L &&yWE ' D?Exxq!!eai 9..y9''#' +,C $ 0 0  IU+y/@/@@! :..y9''#' +,C $ 0 0# -NB r!cURUnURXU5Vs/sH5n[U5RUR U55(dM3UPM7 sn$s snf)a'Return all purviews that could belong to the |MIC|/|MIE|. Filters out trivially-reducible purviews. Args: direction (str): Either |CAUSE| or |EFFECT|. mechanism (tuple[int]): The mechanism of interest. Keyword Args: purviews (tuple[int]): Optional subset of purviews of interest. )r>potential_purviewsr4ryrz)r?rrjpurviewsr>rks r rTransition.potential_purviews{shY'#)#<#<h$0 $07|$$T%9%9)%DE $0   s 2A#A#c^^^^TRTTU5nU(d[TRT5TTS5nO[UUUU4SjU55n[ U5$)a)Return the maximally irreducible cause or effect ratio for a mechanism. Args: direction (str): The temporal direction, specifying cause or effect. mechanism (tuple[int]): The mechanism to be tested for irreducibility. Keyword Args: purviews (tuple[int]): Optionally restrict the possible purviews to a subset of the subsystem. This may be useful for _e.g._ finding only concepts that are "about" a certain subset of nodes. Returns: CausalLink: The maximally-irreducible actual cause or effect. Nc3L># UHnTRTTUT5v M g7frF)r)rrkrrrjr?s r r.Transition.find_causal_link..s/3)1g-- 9g(133)1s!$)rrrmaxr)r?rrjrrmax_rias``` ` r find_causal_linkTransition.find_causal_linksb(**9iJ"4#7#7 #B#,i?G3)133G '""r!cBUR[RX5$)z'Return the actual cause of a mechanism.)rrr<r?rjrs r find_actual_causeTransition.find_actual_causes$$Y__iJJr!cBUR[RX5$)z(Return the actual effect of a mechanism.)rrr=rs r find_actual_effectTransition.find_actual_effects$$Y%5%5yKKr!c&UR"U0UD6$)z8Backwards-compatible alias for :func:`find_causal_link`.)r)r?argskwargss r find_miceTransition.find_mices$$d5f55r!) r+r*r.r7r1r/r6r)r0r>)NFF)FF)(__name__ __module__ __qualname____firstlineno____doc__rCrIrMrQrUrYr\propertyr,rbrerlrorsrvrhrrrrrr~rzrrrrrrrrrrr__static_attributes__r&r!r r#r#-s+\=B6 p(  &((  H DE23@(!"F8 , H@AC P6v *?D#(!#FKL6r!r#c USLa$[R"URU5SS9nUVs/sHnURXUUS9PM nn[ [ SU55$s snf)z?Return the set of all |CausalLinks| of the specified direction.FTnonempty)rrN)r powersetr~rrfilter) transitionr mechanismsrrrjlinkss r directed_accountrs~U^^J$@$@$K-13 $ %$I ##I8.7 $ 9#  % 6$. //  %sA cU[R:wa [X5$[[U[R5[U[R 5-5$)zReturn the set of all causal links for a |Transition|. Args: transition (Transition): The transition of interest. Keyword Args: direction (Direction): By default the account contains actual causes and actual effects. )r BIDIRECTIONALrrr<r=)rrs r accountrsPI+++ 66 #J @#J 0@0@AB CCr!c[UVs/sHo"RPM sn5[UVs/sHo"RPM sn5- $s snfs snf)zReturn the distance between two accounts. Here that is just the difference in sum(alpha) Args: A1 (Account): The first account. A2 (Account): The second account Returns: float: The distance between the two accounts. )sumr)A1A2actions r account_distancersF B/B&B/ 0 B/B&B/ 0 12//s A A c URU5n[XC5n[RSU5 [ X%5n[ [ U[R5UUUUUS9$)z:Find the |AcSystemIrreducibilityAnalysis| for a given cut.zFinished evaluating %s.)rrrpartitioned_accountrr1) rerlogdebugrrrrr)rr1unpartitioned_accountrcut_transitionrrs r _evaluate_cutrse ))#.N!.<II'- 2 HE )E6++,%/   r!c#*# URRnU[RLa[ 5n[ [ U[R5[ U[R55HDn[R"URU55nXS;dM/URU5 Uv MF gURU5nURU5n[XgUR 5Hn[#XUR 5v M g7f)z(A list of possible cuts to a transition.N)r)sizerrr4r _get_cutsr<r=r np_hashable cut_matrixaddr~rzrr,r) rrnyieldedr1cmrjrkrs r rr sAI+++%:y?":y/?/?@BC""3>>!#45B  B B00; ,,Y7' (2(>(>@II*2H2HI I@s BD!A2Dc[R"USS9 [RSU5 U(d![RSU5 [ X5$[ R "URRUR5(d![RSU5 [ X5$[RS5 [X5n[RS5 U(d [RS5 [ X5$[X5n[X0X5nUR5n[RS U5 [RS U5 U$) afReturn the minimal information partition of a transition in a specific direction. Args: transition (Transition): The candidate system. Returns: AcSystemIrreducibilityAnalysis: A nested structure containing all the data from the intermediate calculations. The top level contains the basic irreducibility information for the given subsystem. T)allow_bizCalculating big-alpha for %s...z7Transition %s is empty; returning null SIA immediately.zD%s is not strongly/weakly connected; returning null SIA immediately.z Finding unpartitioned account...zFound unpartitioned account.z?Empty unpartitioned account; returning null AC SIA immediately.z,Finished calculating big-ac-phi data for %s. RESULT: %s)r rrinforr is_weakr)rr0rrrComputeACSystemIrreducibilityrun_sequential)rrrcutsengineresults r siar!s y40HH . ;   !+ -J22    2 2 5 5 * 7 7 9 9  !+ -J22II01#J:II,-    !J22 Z +D * )>MG 33  s*B'C*C9 CCCCCc^[R"U5 U4Sj[XU55n[[ [ SU5SS95$)z7Return a tuple of all irreducible nexus of the network.c3<># UHn[UT5v M g7frF)r)rrrs r rnexus..s" = ;,6C I & & ;rNT)reverse)r is_networkrr2r3r)r)r*r+rsiass ` r nexusr"sB   = { ; =D tT*D9 ::r!c"[R"U5 [RS5 [ XX#5nU(a [ U5nO[ XUSS5n[XS5n[RS5 [RSU5 U$)z'Return the causal nexus of the network.zCalculating causal nexus...r&z"Finished calculating causal nexus.r) r r rrr"rr#rr)r)r*r+rrnull_transitions r causal_nexusr%st  HH *+ 7+ AF V$ ;B8o9HH 12IInf% Mr!c r/n/nSnSnUHnUR[R:XaMURSR [ UR S55URX5R/5 MnUR[R:XaMURSR [ UR S55URXER/5 M[R"UR5 M [[U55Vs/sH nXX%4PM nnU$s snf)z%Format a true |CauseEffectStructure|.z<--z-->z{0:.4f}) rrr<appendr|rrrjrkr=r rangerX)tc cause_list next_listcauseeffectevent true_lists r nice_true_cesr1s JI E F ??ioo -   y//ekk10EF$}}F G __ 0 0 0   i..uU[[!/DE#oov}}F G   u /$C O464U#Y%5646 6sD4cx[RS5 [XX#U5n[U[R US9$)NzCalculating true causes ...r)rrr#rrr<)r)previous_state current_stater9rrs r _actual_causesr6s5HH *+u>J J J OOr!cx[RS5 [XX#U5n[U[R US9$)NzCalculating true effects ...r3)rrr#rrr=)r)r5 next_stater9rrs r _actual_effectsr9s7HH +,GJuMJ I$$ ==r!c^^^ [XUXE5m[XUXE5m[ST55[ST55-m T (dgU 4SjnU"T5mU"T5m[UU4Sj[ T 555$)zCFind all events (mechanisms with actual causes and actual effects).c38# UHoRv M g7frFrjrcs r revents..s@-Q[[-c38# UHoRv M g7frFr<r=s r rr?sA.Q[[.r@r&cn>UVs0sH"nURT;dMURU_M$ sn$s snf)zlFilter out unidirectional occurences and return a dictionary keyed by the mechanism of the cause or effect. r<)actual_causes_or_effectsoactual_mechanismss r r:events..indexsB)A5(@1;;"33 Q(@5 55s22c3H># UHn[TUTU5v M g7frF)r)rm actual_causesactual_effectss r rr?s,53Q}Q'):;;3s")r6r9r4r2r3) r)r4r5r8r9rr:rIrJrEs @@@r eventsrKs#7M#(6M$WZ%*8N@-@@A.AAB 5-(M>*N 5 !235 55r!cURnURnURn[X1XRU5nU(d[R S5 g[ UVs/sHowRPM snUVs/sHowRPM sn-5n[R S5 [RSU5 U$s snfs snf)aSet of all sets of elements that have true causes and true effects. .. note:: Since the true |CauseEffectStructure| is always about the full system, the background conditions don't matter and the subsystem should be conditioned on the current state. z%Finished calculating, no echo events.Nz!Finished calculating true events.r) r)r0r8rKrrr2 actual_cause actual_effectr) subsystemr4r8r)r9r8_eventsr/rs r true_cesrQsG  " "E OOEWeGG  89 G?FHH 01IInf% M ==s B>3C cU(aURRnO6U(aUnO,[R"X5nURRn[ XX#U5$)aqReturn all mechanisms that have true causes and true effects within the complex. Args: network (Network): The network to analyze. previous_state (tuple[int]): The state of the network at ``t - 1``. current_state (tuple[int]): The state of the network at ``t``. next_state (tuple[int]): The state of the network at ``t + 1``. Keyword Args: indices (tuple[int]): The indices of the major complex. major_complex (AcSystemIrreducibilityAnalysis): The major complex. If ``major_complex`` is given then ``indices`` is ignored. Returns: tuple[Event]: List of true events in the major complex. )rOr0r major_complexrK)r)r4r5r8indicesrSr9s r true_eventsrUsP*''44 --gE ''44 '=e LLr!c U(aURRnO6U(aUnO,[R"X5nURRn[ [ R "USS95nURn[XX#XS9$)aSet of all mechanisms that are in the major complex but which have true causes and effects within the entire network. Args: network (Network): The network to analyze. previous_state (tuple[int]): The state of the network at ``t - 1``. current_state (tuple[int]): The state of the network at ``t``. next_state (tuple[int]): The state of the network at ``t + 1``. Keyword Args: indices (tuple[int]): The indices of the major complex. major_complex (AcSystemIrreducibilityAnalysis): The major complex. If ``major_complex`` is given then ``indices`` is ignored. Returns: tuple(actions): List of extrinsic events in the major complex. Trr3)rOr0rrSlistr rrK) r)r4r5r8rTrSmc_nodesr all_nodess r extrinsic_eventsrZsu& **77 --gE  **77ennX=>J$$I '= 44r!)FFFr)NN):rlogging itertoolsrmathrrnumpyrrrrr r r r r modelsrrrrrrrrrrrrrrOr getLoggerrrr#rrrrrrrparallel MapReducerrr"r%r1r6r9rKrQrUrZr&r!r rds- "   ((((&  !- P6P6p HM$ 0#,"9"9C, 2 &33&J*(55)XG$4$4$>$>>(++;%220,$P %=5:6-1MB264r!