DotNETNEAT 1.0.2

NEAT

Uživatelská dokumentace

Stažení balíčku

Instalování balíčku:

dotnet add package DotNETNEAT --version 1.0.0

Požadavky

Cílový framework

• .NET 8.0

Příklad použití:

• Problém: pro 10 náhodných vstupů postav takovou síť, která vydá největší číslo mezi 0 - 1

//Creating a logger for console.
Action<ILoggingBuilder> action = (
       builder => _ = builder.AddConsole().SetMinimumLevel(LogLevel.Information));
var log = LoggerFactory.Create(action);

List<double> input = new List<double>();

//Add random values to list
for (int i = 0; i < 10; i++)
{
    Random random = new Random();
    var num = random.NextDouble();
    input.Add(num);
}

Console.ReadLine();
//Building neat
var b = new NeatBuilder().AddLogger(action).
    //solves this easy problem almost instantly due fully connected individuals
    //.SetInitialConnection(GenomeInitialConnection.Full) 
    SetInitialConnectin(GenomeInitialConnection.Random).
    SetCrossOverMutationProbability(0.1).SetMutationProbabilityNewConnection(0.1)
    .SetMutationProbabilityWeightShift(0.1).SetMutationProbabilityNewNode(0.1);

//Definition of a "fitness" function
Action<Individual> individualEvaluator = individual =>
{
    var temp = individual.Calculate(input);
    var score = temp[0];
    individual.Fitness = score;
};

using (NEAT neat = b.Build())
{
    neat.Run(input.Count, 1, 150, 150, individualEvaluator);
    Console.WriteLine($"Best individual {neat.BestIndividual!.Fitness}");
}

Programátorská dokumentace

ActivationFunctions.cs

Statická tříta obsahuje statické delegáty na známe aktivační funkce se vstupním parametrem "x".

• $Sigmoid(x) = \frac{1}{1+e^{-x}}$

• $ReLu(x) = \max(0, x)$

• $Tanh(x) = \tanh(x)$

• $Linear(x) = x$

GetActivationFunctionDelegate(ActivationFunctions activ function)

Vrátí příslušný delegát na funkci z výčtového typu

ActivationFunctionEnum.cs

Výčtový typ obsahující aktivační funkce, které jsou implementované v knihovně. Zatím to jsou Sigmoid, ReLu, Tanh a Linear.

ConnectionGeneBuilder.cs

Internal builder třída, obsahující metody, které jsou potřeba pro vytvoření instance ConnectionGene

Defaultní instance má nastavený logger z konstruktoru, váhu hrany nastavenou na 1, inovační čostlo na 0 a hrana je aktivovaná.

SetEnableState(bool enabled)

Změní stav aktivace hrany

AddInovationNumnber(uint inovationNumber)

Přidá inovační číslo ke stavěné hraně.

AddWeight

Upravý váhu stavěné hrany.

Build(NodeGene from, NodeGene toGene)

Postavý a vrátí hranu s parametry v buildru a tato hrana vede od from do toGene.

GenomeBuilder.cs

Internal třída, která slouží pro stavění Genomů.

AddActivationFunction(Func<double, double> activationFunction )

Přidá genomu uživatelsky definovanou aktivační funkci.

AddActivationFunction(ActivationFunctions.ActivationFunctions activationFunction)

Build(NEAT neat)

Postavý genon s parametry daný v buildru.

AddNodeGenes(IEnumerable<NodeGene> genes)

Vytvoří nový list s geny specifikovaný v argumentu této funkce.

AppendGenes(IEnumerable<NodeGene> genes)

Přidá geny k již existujicím vrcholům, pokud neexistují vytvoří se znova.

SetInitialConnection(GenomeInitialConnection connection)

Nastaví počáteční spojení stavěného genomu.

NeatBuilder.cs

Pomocí NeatBuilderu si nastaví různe parametry pro celkový Neat algoritmus.

SetMutationProbabilityNewConnection(double probability)

Nastaví novou pravděpodobnost pro vytvoření nového spojení v Genomu.

SetMutationProbabilityNewNode(double probability)

Nastaví novou pravděpodobnost pro vytvoření nového vrcholu.

SetMutationProbabilityWeightShift(double probability)

Nastaví novou pravděpodobnost pro posunu váhy hrany.

SetMutationProbabilityRandomWeight(double probability)

Nastaví novou pravděpodobnost pro zvolení váhy hrany náhodně.

SetMutationProbabilityToggleConnection(double probability)

Nastaví novou pravděpodobnost pro aktivaci nebo deaktivaci hrany.

SetCrossOverMutationProbability(double probability)

Nastaví novou pravděpodobnost pro mutaci genomů.

NEAT Build()

Postaví Celý Neat s parametry zvolené v Builderu.

SetInitialConnectin(GenomeInitialConnection InitialConnection)

Nastaví počáteční spojené genomů.

AddLogger(Action<ILoggingBuilder> action)

Nastaví logger pro logování v Neatu.

AddActivationFunction(Func<double,double> activationFunction)

Nastaví uživatelsky definovanou aktivační funkci.

AddActivationFunction(ActivationFunctions.ActivationFunctions activationFunction)

Nastaví aktivační funkce.

IsProbability(double value)

Zjistí jestli hodnota je pravděpodobnost čili jestli je hodnota mezi 0-1 včetně mezí.

NodeGeneBuilder.cs

Pomocí nodeGeneBuilderu nastavujeme parametry pro vytvoření genů v Neatu.

AddConnectionOrder(double connectionOrder)

Nastaví číslo spojení pro genu. Tato hodnota určuje pozici genu v Genomu, podle kterého se pak počítá fitness celého genomu.

AddInovationNumber(uint inovationNumber)

Nastaví inovační číslo genu. Toto číslo říká pořadí vytvořeného genomu.

AddNodeType(NodeGeneType type)

Nastaví typ genomu.

Build()

Postaví genom s parametry uvedené v builderovi.

Builder.cs

Abstraktní třída pro určená pro lehčí vytváření builderů.

Connection.cs

Určuje orientovanou hranu v sítí. Obsahuje stav jestli je aktivní, váhu a informaci z jakého vrcholu vede a do jakého vrcholu vede.

Toggle()

Změní aktivaci hrany.

Toggle(bool state)

Nastaví aktivace hrany na stav.

ConnectionGene.cs

Rozšiřuje třídu Connection inovační třídu a spojení vede mezi NodeGene místo Gene. Obsahuje inovační číslo hrany.

CopyConnectionGene

Vytvoří novou instanci ConnectionGene se stejnými parametry.

CreationOnSameNodesException.cs

Výjimka která se má vyhazovat, když proběhne pokus postavení hrany na mezi 2 stejnými vrcholy.

InvalidNodeCountException.cs

Výjimka, která vznikne, pokud uživatel zadá jiný počet vstupní nebo výstupní vrstvy než je v NEATu potřeba.

BoundaryCheck

ThrowIfNegativeOrZero (int value, string? paramName = null)

Vyhodí výjimku argumentOutOfRange když hodnota v argumentu je menší nebo rovno nule

NeatNotRun

Pokus o přístup k prvkům neatu bez spuštění algoritmu NEAT.

ConnectionGeneExtension.cs

GetNodeGenes(this ConnectionGene connectionGene)

Ze vznikhlého spojení vrátí vrchol tuple (from, to).

IListExtenstions.cs

GetRandomElement<T>(this IList<T> list)

Vrátí náhodný prvek z IListu nebo default pokud list je prázdný.

SetListEXtentions

GetWeightedRandomElement(this IList<Species> list)

Vrátí vážený náhodný druh.

Genome.cs

Genome je sít s vrcholy a hrany.

Distance(Genome other)

Spočítá jak moc se strukutra this genomu a druhého liší. Algoritmus:

1)Uspořádají se hrany genomů podle inovačních čísel.
2)Pokud se inovační čísla hran rovnaji, tak vážený průměr je absolutní hodnota váh hrany.
3) Pokud inovační číslo hrany prvního genomu je vetší než inovační číslo hrany druhého genomu, tak se podíváme na další hranu druhého genomu.
4) Jinak posuneme hranu prvního genomu
5) Vrať vzdálenost genomů

Kde vzdálenost genomů je $$ \delta = \frac{c_1 \cdot E}{N} + \frac{c_2 \cdot D}{N} + W $$ a c1 je ExcessFactor, c2 je disjointFactor W je vážený průměr rozdílu vhodných genů, E je počet přebytkových genů, D je počet disjunktivních prvků a N je maximální velikost hran prvního a druhého genomu.

CrossOver(Genome x, Genome y)

1)Pro každou hranu x a y se podíváme na inovační číslo, pokud jsou stejné, tato hrana bude i v potomku.
2) Pokud hrana v x má větší inov. číslo než y, tak se posune index pouze u x
3) jinak posuň index u y.

Mutate

Provede mutaco celého genomu. Konkrétně

• Přidání hrany
• Přičtení váhy k existující váze
• Vytvoří novou váhu pro náhodnou hranu.
• Aktivace nebo deaktivace hrany. Šance na provedení konkrétní mutace si uživatel volí sám.

NewNodeGeneMutation()

Vytvoří nový vrchol tak, že vybere náhodnou hranu pokud existuje. Mezi 2 vrcholy této hrany vytvoří nový vrchol. Původní hranu smaže, první čast podrozdělené hrany má defaultní parametry, druhá část má vlastnosti smazané hrany.

ToggleConnectionGeneMutation()

Aktivuje nebo deaktivuje hranu.

AddWeightMutation()

Přičte faktor k k náhodný hraně

AddConnectionMutation()

K dosut nespojeným 2 vrcholům vytvoří nové spojení.

RandomWeightMutation()

Náhodné hraně z genomu změní váhu na RandomWeight faktor.

CreateConection(GenomeInitialConnection config)

Podle typu configu vytvoří počáteční spojení vrcholů v genomu.

• Random - vytvoří náhodné spojení
• Empty - Nevytvoří žádné spojení
• Full - Vytvoří husté spojení. Tj každý vrchol je spojený s každým.

ConnectAllConnections

Spojí všechny vrcholy s každým.

ConnectRandomlyNodes

Spojý vrcholy náhodně

SetListWrapper.cs

Pomocná datová strukura. Je to kombinace listu a hashsetu. Umožňuje rychlý přístup přes hash kód a zároveň přes index.

NodeCalculator.cs

Slouží pro vyhodnocování sítě v jedinci. Při inicializi rozdělí genom na vstupní, skryté a výstupní vrstvy. Skrité vrstvy jsou seřazený vzestupně podle connection order.

CalculateFitness(IList<double> input)

Spočte setřízenou sít.

Individual.cs

Jedná se o wrapper Genomu. Obsahuje fitness, do jakého druhu patří.

SetSpecie(Specie specie)

Nastaví do jakého druhu tento jedinec patří.

RegenerateCalculator()

Vygeneruje novou kalkulačku, protože se sít genomu směnila po růzých mutací.

Calculate(List<double> input)

Vypočte fitness jedince.

Distance (Individual other)

Wrapper funkce pro distance genomu.

Mate(Individual other)

Wrapper funkce pro křížení genomů v jedinci.

TrySetSpecie(IList<Species> species)

Pokusí se přidat tohoto jedince do náhodného druhu. Vrátí True pokud byl tento jedinec úspěšně přidaný.

ISetList.cs

Interface pro SetList. Obsahuje metody pro získání HashSet a listu.

Species.cs

Reprezentuje druh v Neatu. Každý druh je reprezentován přes jedince.

TryAddIntoSpecie(Individual individual)

Pokud je vzdálenost jedince a reprezentanta tohoto druhu menší než rozdíl povolené vzdálenosti zadané od uživatelem, tak je jedinec přidaný a vrátí True.

Add(Individial individual)

Přidá jedince do druhu bez kontroli vzdálenosti s reprezentantem.

Extinct()

Tento druh zahyne, tedy se pro všechny jedince nastaví druh na null.

EvaluateSpecieFitness()

Ohodnotí fitness celkové populace

Reset()

Vybere se náhodný jedinec z populace, ten bude reprezentant a zbytek jedinců z této populace se nastaví na null.

Kill(double keepPercentage)

Zabije 1 - keepPercentage jedinců

Mate()

vybere 2 náhodné jedince z druhu pokud neexistujou vezme se reprezentant. Tyto náhodné jedince rozmnoží.

IGene.cs

Interface pro geny v neatu.

Node.cs

Vrchol v síti. Obsahuje výstupní hodnotu vrcholu, množinu hran se kterýma je spojený, Uvažuji pouze spětné hrany.

CalculateOutputOfNode(Func<double, double> activationFunction)

Spočte výstup pro daný vrchol. Přes aktivační funkci

NodeBase.cs

Abstraktní třída pro vrchol. Obsahuje Typ vrcholu, spojení.

NodeGene.cs

Reprezentuje Vrchol genu. Dědí od Node, obsahuje inovační číslo a má overridnuté metody pro rovnáse, hash a rovnost.

NodeGeneTypeEnum.cs

Výčtový typ pro reprezentaci Typu vrcholu. Konkrétně

• Input - reprezentuje vstupní vrchol
• Hidden - reprezentuje vrchol ve skrýté vrstvě (Vrchol položený mezi vstupní a výstupními vrcholy)
• Output - Výstupní vrchol.

NEAT.cs

Hlavní třída se kterou uživatel operuje. Lze zkonstruovat pouze přes NeatBuilderu. Obsahuje pravděpodobnosti mutací, hodnoty faktorů a parametrů pro síť.

CreateNewNodeGene(double connectionOrder, NodeGeneType type)

Vytvoří nový NodeGene s hodnotama v argumentu.

CreateNewNodeGene(NodeGene from, NodeGene to, NodeGeneType type = NodeGeneType.Hidden)

Pokusí se vytvořit nový node gene. Pokud takový nodeGene který ma stejný from a to gene, tak nevytvoří nový nodegene s novým inovačním číslem, ale vrátí nový nodegene s korespondujícím inovačním číslem, jinak vytvoří nový node gene s novým inovačním číslem.

CreateEmptyGenome()

Vytvoří nový prázdný genome.

CreateNewConnectionGene(NodeGene nodeX, NodeGene nodeY)

Vytvoří nový spojení mezi vrcholy.

Run(int InputSize, int OutputSize, int Individuals, int Generations, Action<Individual> genomeEvaluation)

Spustí algoritmus neatu.

Začne počáteční populaci 
Evaluace  
Selekce
Crossover
Mutace   
Speciation
Opakuj

GenerateSpecies()

Vygeneruje druhy v neatu.

EvaluateSpecie()

Ohodnotí druhy.

TryFindingSpecie(Individual individual)

Pokusí se najít druh pro jedince, vrátí false pokud nebyl nalezen.

ReducePopulation()

Zredukuje populaci na velikost určenou uživatelem.

RemoveExtinctSpecies()

Odstraní druhy, které mají nejvýše 1 jedince.

Mate()

Rozmnoží všechny jedince v neatu.

MainLoop(Action<Individual> genomeEvaluation)

Vyhodnotí všechny jedince, následně je vyvine.

List<Individual> GetIndividuals()

Vrátí všechny jednotlivce v neatu. Pokud je tato metoda zavolaná před spuštěním NEAT.run, tak se vyhodí výjimka NeatNotRunException.

Statistics.cs

Pomocné funkce pro počítání statistiky NEAT.cs

Mean(List<Individual> individuals)

Spočte průměr jedinců v populaci.

SquareDifferences( List<Individual> individuals, double mean)

Z průměru jedinců a jedinců spočte čtvercový rozdíl

StdDev(List<Individual> individuals,double mean)

Z průměru jedinců a jednotlivů a vrátí odchylku.

GenomConfiguration.cs

Výčtový typ pro konfigurace počátečního genomu.

• Empty - Žádné hrany v počátečním genomu nejsou specifikované
• Full - Všechny vrcholy v genomu jsou propojené.
• Random - vrcholy v genomu jsou náhodně propojené.

ILoggable

Interface pro snadnější logování informací v neatu