neuralogic.core.builder package

Submodules

neuralogic.core.builder.builder module

class Builder(settings: SettingsProxy)[source]

Bases: object

Builder is responsible for grounding, neuralizing, and building models from models and sources.

build_model(parsed_model: Any, settings: SettingsProxy) → Any[source]

Builds a neural model from the parsed model.

Parameters:

parsed_model (Any) – The parsed model.
settings (SettingsProxy) – The settings proxy.

Returns:

The built neural model.

Return type:

Any

build_model_from_file(settings: SettingsProxy, filename: str) → Any[source]

Builds a model from a file.

Parameters:

settings (SettingsProxy) – The settings proxy.
filename (str) – The path to the model file.

Returns:

The built model.

Return type:

Any

static get_builders(settings: SettingsProxy) → Any[source]

ground_from_logic_samples(parsed_model: Any, logic_samples: list[Any], progress: bool) → Any[source]

Grounds the model from the provided logic samples.

Parameters:

parsed_model (Any) – The parsed model.
logic_samples (list[Any]) – The logic samples.
progress (bool) – Whether to show progress.

Returns:

The grounded logic samples.

Return type:

Any

ground_from_sources(parsed_model: Any, sources: Sources, progress: bool) → Any[source]

Grounds the model from the provided sources.

Parameters:

parsed_model (Any) – The parsed model.
sources (Sources) – The logic sources.
progress (bool) – Whether to show progress.

Returns:

The grounded logic samples.

Return type:

Any

neuralize(groundings, progress: bool, length: int | None) → list[NeuralSample][source]

Neuralizes the grounding samples.

Parameters:

groundings (Any) – The logic groundings to neuralize.
progress (bool) – Whether to show progress.
length (int, optional) – The total number of groundings. Default: None.

Returns:

The neuralized samples.

Return type:

list[NeuralSample]

stream_to_list(stream: Any) → list[source]

Converts a Java stream to a Python list.

Parameters:: stream (Any) – The Java stream to convert.
Returns:: The converted Python list.
Return type:: list

neuralogic.core.builder.components module

class Atom(atom: Any, substitutions: dict[str, Any])[source]

Bases: object

Represents an atom in the logic program, often corresponding to a node in the neural network.

property arity: int

node_type() → NeuronType[source]

Returns the type of the neuron.

Returns:: The type of the neuron.
Return type:: NeuronType

property predicate: str

substitutions

class Grounding(grounding: Any)[source]

Bases: object

Represents a grounded model, providing access to grounded atoms and facts.

property atoms: dict[str, dict[tuple[str, ...], Any]]

draw(filename: str | None = None, show: bool = True, img_type: str = 'png', value_detail: int = 0, graphviz_path: str | None = None, *args: Any, **kwargs: Any) → Any[source]

Draws the grounding.

Parameters:

filename (str, optional) – The filename to save the drawing to. Default: None.
show (bool) – Whether to show the drawing. Default: True.
img_type (str) – The image type. Default: “png”.
value_detail (int) – The level of detail for values. Default: 0.
graphviz_path (str, optional) – The path to the Graphviz executable. Default: None.

Returns:

The drawing data or image object.

Return type:

Any

get_atoms(literal: Any) → list[Atom][source]

Returns a list of grounded atoms matching the provided literal.

Parameters:: literal (Any) – The literal to match.
Returns:: The list of matching grounded atoms.
Return type:: list[Atom]

class NeuralSample(sample: Any)[source]

Bases: object

Represents a single training or testing sample, containing the query and its associated neural network (evidence).

draw(filename: str | None = None, show: bool = True, img_type: str = 'png', value_detail: int = 0, graphviz_path: str | None = None, *args: Any, **kwargs: Any) → Any[source]

Draws the neural sample.

Parameters:

filename (str, optional) – The filename to save the drawing to. Default: None.
show (bool) – Whether to show the drawing. Default: True.
img_type (str) – The image type. Default: “png”.
value_detail (int) – The level of detail for values. Default: 0.
graphviz_path (str, optional) – The path to the Graphviz executable. Default: None.

Returns:

The drawing data or image object.

Return type:

Any

get_fact(fact: Any) → list[Neuron][source]

Returns the neuron corresponding to the provided fact.

Parameters:: fact (Any) – The fact to look for.
Returns:: The matching fact neuron(s).
Return type:: list[Neuron]

get_neurons(literal: Any, neuron_type: NeuronType | None = NeuronType.Atom) → list[Neuron][source]

Returns a list of neurons matching the provided literal and neuron type.

Parameters:

literal (Any) – The literal to match.
neuron_type (NeuronType, optional) – The type of neurons to search for. Default: NeuronType.Atom.

Returns:

The list of matching neurons.

Return type:

list[Neuron]

property neurons: dict[str, dict[str, dict[tuple[str, ...], Any]]]

set_fact_value(fact: Any, value: float) → int[source]

Sets the value of a specific fact in the sample.

Parameters:

fact (Any) – The fact to set the value for.
value (float) – The value to set.

Returns:

The index of the fact neuron, or -1 if not found.

Return type:

int

property target: float | list | ndarray

class Neuron(neuron: Any, substitutions: dict[str, Any])[source]

Bases: Atom

Represents a neuron in the neural network, extending the Atom class with value and gradient properties.

property gradient: float | list | ndarray

substitutions

property value: float | list | ndarray

class NeuronType(value)[source]

Bases: str, Enum

Enum representing different types of neurons in the neural network.

Aggregation = 'AggregationNeuron'

Atom = 'AtomNeuron'

Fact = 'FactNeuron'

Negation = 'NegationNeuron'

Rule = 'RuleNeuron'

SplittableAggregation = 'SplittableAggregationNeuron'

WeightedAtom = 'WeightedAtomNeuron'

WeightedRule = 'WeightedRuleNeuron'

neuralogic.core.builder.dataset module

class BuiltDataset(samples: list[NeuralSample], batch_size: int)[source]

Bases: object

BuiltDataset represents an already built dataset - that is, a dataset that has been grounded and neuralized.

class GroundedDataset(groundings, builder: Builder)[source]

Bases: object

GroundedDataset represents grounded examples that are not neuralized yet.

neuralize(*, batch_size: int = 1, progress: bool = False) → BuiltDataset[source]

neuralogic.core.builder.dataset_builder module

class DatasetBuilder(parsed_model: Any, java_factory: JavaFactory)[source]

Bases: object

DatasetBuilder is responsible for grounding and neuralizing datasets.

build_dataset(dataset: BaseDataset | GroundedDataset, settings: SettingsProxy, *, batch_size: int = 1, learnable_facts: bool = False, progress: bool = False) → BuiltDataset[source]

Builds the dataset (does grounding and neuralization).

Parameters:

dataset (datasets.BaseDataset | GroundedDataset) – The dataset to build.
settings (SettingsProxy) – The settings proxy.
batch_size (int) – The batch size. Default: 1.
learnable_facts (bool) – Whether facts are learnable. Default: False.
progress (bool) – Whether to show progress. Default: False.

Returns:

The built dataset.

Return type:

BuiltDataset

build_examples(examples: Iterable[Any], examples_builder: Any, learnable_facts: bool = False) → tuple[list[Any], bool][source]

Builds examples from the provided examples and examples builder.

Parameters:

examples (Iterable) – The examples to build.
examples_builder (Any) – The examples builder.
learnable_facts (bool) – Whether facts are learnable. Default: False.

Returns:

A tuple containing the list of built logic samples and a boolean indicating if there are examples with queries.

Return type:

tuple[list[Any], bool]

build_queries(queries: Iterable[Any], query_builder: Any) → tuple[list[Any], bool][source]

Builds queries from the provided queries and query builder.

Parameters:

queries (Iterable) – The queries to build.
query_builder (Any) – The query builder.

Returns:

A tuple containing the list of built logic samples and a boolean indicating if there is one query per example.

Return type:

tuple[list[Any], bool]

ground_dataset(dataset: BaseDataset, settings: SettingsProxy, *, batch_size: int = 1, learnable_facts: bool = False, progress: bool = False, raw_groundings: bool = False) → GroundedDataset | Any[source]

Grounds the dataset.

Parameters:

dataset (datasets.BaseDataset) – The dataset to ground.
settings (SettingsProxy) – The settings proxy.
batch_size (int) – The batch size. Default: 1.
learnable_facts (bool) – Whether facts are learnable. Default: False.
progress (bool) – Whether to show progress. Default: False.
raw_groundings (bool) – Whether to return raw groundings. Default: False.

Returns:

The grounded dataset or raw groundings.

Return type:

GroundedDataset | Any

static merge_queries_with_examples(queries: list[Any], examples: list[Any], one_query_per_example: bool, example_queries: bool = True) → list[Any][source]

Merges queries with their corresponding examples.

Parameters:

queries (list[Any]) – The list of queries.
examples (list[Any]) – The list of examples.
one_query_per_example (bool) – Whether there is one query per example.
example_queries (bool) – Whether examples contain queries. Default: True.

Returns:

The list of merged logic samples.

Return type:

list[Any]

samples_to_examples_and_queries(samples: list[Any]) → tuple[Iterable[Any], Iterable[Any]][source]

Converts a list of samples to two lists: examples and queries.

Parameters:: samples (list[Any]) – The list of samples.
Returns:: A tuple containing the iterable of examples and the iterable of queries.
Return type:: tuple[Iterable[Any], Iterable[Any]]

Module contents

class Atom(atom: Any, substitutions: dict[str, Any])[source]

Bases: object

Represents an atom in the logic program, often corresponding to a node in the neural network.

property arity: int

node_type() → NeuronType[source]

Returns the type of the neuron.

Returns:: The type of the neuron.
Return type:: NeuronType

property predicate: str

substitutions

class Builder(settings: SettingsProxy)[source]

Bases: object

Builder is responsible for grounding, neuralizing, and building models from models and sources.

build_model(parsed_model: Any, settings: SettingsProxy) → Any[source]

Builds a neural model from the parsed model.

Parameters:

parsed_model (Any) – The parsed model.
settings (SettingsProxy) – The settings proxy.

Returns:

The built neural model.

Return type:

Any

build_model_from_file(settings: SettingsProxy, filename: str) → Any[source]

Builds a model from a file.

Parameters:

settings (SettingsProxy) – The settings proxy.
filename (str) – The path to the model file.

Returns:

The built model.

Return type:

Any

static get_builders(settings: SettingsProxy) → Any[source]

ground_from_logic_samples(parsed_model: Any, logic_samples: list[Any], progress: bool) → Any[source]

Grounds the model from the provided logic samples.

Parameters:

parsed_model (Any) – The parsed model.
logic_samples (list[Any]) – The logic samples.
progress (bool) – Whether to show progress.

Returns:

The grounded logic samples.

Return type:

Any

ground_from_sources(parsed_model: Any, sources: Sources, progress: bool) → Any[source]

Grounds the model from the provided sources.

Parameters:

parsed_model (Any) – The parsed model.
sources (Sources) – The logic sources.
progress (bool) – Whether to show progress.

Returns:

The grounded logic samples.

Return type:

Any

neuralize(groundings, progress: bool, length: int | None) → list[NeuralSample][source]

Neuralizes the grounding samples.

Parameters:

groundings (Any) – The logic groundings to neuralize.
progress (bool) – Whether to show progress.
length (int, optional) – The total number of groundings. Default: None.

Returns:

The neuralized samples.

Return type:

list[NeuralSample]

class BuiltDataset(samples: list[NeuralSample], batch_size: int)[source]

Bases: object

BuiltDataset represents an already built dataset - that is, a dataset that has been grounded and neuralized.

class DatasetBuilder(parsed_model: Any, java_factory: JavaFactory)[source]

Bases: object

DatasetBuilder is responsible for grounding and neuralizing datasets.

build_dataset(dataset: BaseDataset | GroundedDataset, settings: SettingsProxy, *, batch_size: int = 1, learnable_facts: bool = False, progress: bool = False) → BuiltDataset[source]

Builds the dataset (does grounding and neuralization).

Parameters:

dataset (datasets.BaseDataset | GroundedDataset) – The dataset to build.
settings (SettingsProxy) – The settings proxy.
batch_size (int) – The batch size. Default: 1.
learnable_facts (bool) – Whether facts are learnable. Default: False.
progress (bool) – Whether to show progress. Default: False.

Returns:

The built dataset.

Return type:

BuiltDataset

build_examples(examples: Iterable[Any], examples_builder: Any, learnable_facts: bool = False) → tuple[list[Any], bool][source]

Builds examples from the provided examples and examples builder.

Parameters:

examples (Iterable) – The examples to build.
examples_builder (Any) – The examples builder.
learnable_facts (bool) – Whether facts are learnable. Default: False.

Returns:

A tuple containing the list of built logic samples and a boolean indicating if there are examples with queries.

Return type:

tuple[list[Any], bool]

build_queries(queries: Iterable[Any], query_builder: Any) → tuple[list[Any], bool][source]

Builds queries from the provided queries and query builder.

Parameters:

queries (Iterable) – The queries to build.
query_builder (Any) – The query builder.

Returns:

A tuple containing the list of built logic samples and a boolean indicating if there is one query per example.

Return type:

tuple[list[Any], bool]

ground_dataset(dataset: BaseDataset, settings: SettingsProxy, *, batch_size: int = 1, learnable_facts: bool = False, progress: bool = False, raw_groundings: bool = False) → GroundedDataset | Any[source]

Grounds the dataset.

Parameters:

dataset (datasets.BaseDataset) – The dataset to ground.
settings (SettingsProxy) – The settings proxy.
batch_size (int) – The batch size. Default: 1.
learnable_facts (bool) – Whether facts are learnable. Default: False.
progress (bool) – Whether to show progress. Default: False.
raw_groundings (bool) – Whether to return raw groundings. Default: False.

Returns:

The grounded dataset or raw groundings.

Return type:

GroundedDataset | Any

static merge_queries_with_examples(queries: list[Any], examples: list[Any], one_query_per_example: bool, example_queries: bool = True) → list[Any][source]

Merges queries with their corresponding examples.

Parameters:

queries (list[Any]) – The list of queries.
examples (list[Any]) – The list of examples.
one_query_per_example (bool) – Whether there is one query per example.
example_queries (bool) – Whether examples contain queries. Default: True.

Returns:

The list of merged logic samples.

Return type:

list[Any]

class GroundedDataset(groundings, builder: Builder)[source]

Bases: object

GroundedDataset represents grounded examples that are not neuralized yet.

neuralize(*, batch_size: int = 1, progress: bool = False) → BuiltDataset[source]

class Grounding(grounding: Any)[source]

Bases: object

Represents a grounded model, providing access to grounded atoms and facts.

property atoms: dict[str, dict[tuple[str, ...], Any]]

draw(filename: str | None = None, show: bool = True, img_type: str = 'png', value_detail: int = 0, graphviz_path: str | None = None, *args: Any, **kwargs: Any) → Any[source]

Draws the grounding.

Parameters:

filename (str, optional) – The filename to save the drawing to. Default: None.
show (bool) – Whether to show the drawing. Default: True.
img_type (str) – The image type. Default: “png”.
value_detail (int) – The level of detail for values. Default: 0.
graphviz_path (str, optional) – The path to the Graphviz executable. Default: None.

Returns:

The drawing data or image object.

Return type:

Any

get_atoms(literal: Any) → list[Atom][source]

Returns a list of grounded atoms matching the provided literal.

Parameters:: literal (Any) – The literal to match.
Returns:: The list of matching grounded atoms.
Return type:: list[Atom]

class NeuralSample(sample: Any)[source]

Bases: object

Represents a single training or testing sample, containing the query and its associated neural network (evidence).

draw(filename: str | None = None, show: bool = True, img_type: str = 'png', value_detail: int = 0, graphviz_path: str | None = None, *args: Any, **kwargs: Any) → Any[source]

Draws the neural sample.

Parameters:

filename (str, optional) – The filename to save the drawing to. Default: None.
show (bool) – Whether to show the drawing. Default: True.
img_type (str) – The image type. Default: “png”.
value_detail (int) – The level of detail for values. Default: 0.
graphviz_path (str, optional) – The path to the Graphviz executable. Default: None.

Returns:

The drawing data or image object.

Return type:

Any

get_fact(fact: Any) → list[Neuron][source]

Returns the neuron corresponding to the provided fact.

Parameters:: fact (Any) – The fact to look for.
Returns:: The matching fact neuron(s).
Return type:: list[Neuron]

get_neurons(literal: Any, neuron_type: NeuronType | None = NeuronType.Atom) → list[Neuron][source]

Returns a list of neurons matching the provided literal and neuron type.

Parameters:

literal (Any) – The literal to match.
neuron_type (NeuronType, optional) – The type of neurons to search for. Default: NeuronType.Atom.

Returns:

The list of matching neurons.

Return type:

list[Neuron]

property neurons: dict[str, dict[str, dict[tuple[str, ...], Any]]]

set_fact_value(fact: Any, value: float) → int[source]

Sets the value of a specific fact in the sample.

Parameters:

fact (Any) – The fact to set the value for.
value (float) – The value to set.

Returns:

The index of the fact neuron, or -1 if not found.

Return type:

int

property target: float | list | ndarray

class Neuron(neuron: Any, substitutions: dict[str, Any])[source]

Bases: Atom

Represents a neuron in the neural network, extending the Atom class with value and gradient properties.

property gradient: float | list | ndarray

substitutions

property value: float | list | ndarray

class NeuronType(value)[source]

Bases: str, Enum

Enum representing different types of neurons in the neural network.

Aggregation = 'AggregationNeuron'

Atom = 'AtomNeuron'

Fact = 'FactNeuron'

Negation = 'NegationNeuron'

Rule = 'RuleNeuron'

SplittableAggregation = 'SplittableAggregationNeuron'

WeightedAtom = 'WeightedAtomNeuron'

WeightedRule = 'WeightedRuleNeuron'