Skip to content

models

Models for job management.

This module defines data classes for various job management settings and results.

RunInstance dataclass

Represents a single instance of a computational run, storing relevant data and metadata associated with the run.

Attributes:

Name Type Description
run_location str

The directory where the run will be executed.
id str

The identifier for a run instance.
command str

The executable command to run (optional).
args List[str]

The arguments to pass to the command (optional).

Methods:

Name Description
to_dict

Converts the RunInstance object into a JSON-serializable dictionary.
get_command_with_args

Returns the command and arguments for execution.
Source code in src/mada_tools/simulation/simutils/models.py 
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
@dataclass
class RunInstance:
    """
    Represents a single instance of a computational run, storing relevant data
    and metadata associated with the run.

    Attributes:
        run_location (str): The directory where the run will be executed.
        id (str): The identifier for a run instance.
        command (str): The executable command to run (optional).
        args (List[str]): The arguments to pass to the command (optional).

    Methods:
        to_dict: Converts the RunInstance object into a JSON-serializable dictionary.
        get_command_with_args: Returns the command and arguments for execution.
    """

    run_location: str
    id: str
    command: str = None
    args: List[str] = None

    def to_dict(self) -> Dict:
        """
        Converts the RunInstance object into a JSON-serializable dictionary.

        Returns:
            A dictionary representation of the RunInstance object.
        """
        result = {"id": self.id, "run_location": self.run_location}

        # Include command and args if they are set
        if self.command:
            result["command"] = self.command
        if self.args:
            result["args"] = self.args

        return result

    @classmethod
    def from_dict(cls, data: Dict) -> "RunInstance":
        """
        Creates a RunInstance object from a dictionary.

        Args:
            data: Dictionary containing run instance data

        Returns:
            RunInstance object with data from the dictionary
        """
        return cls(
            run_location=data.get("run_location"),
            id=data.get("id"),
            command=data.get("command"),
            args=data.get("args"),
        )

    def __str__(self) -> str:
        """
        Returns a human-readable string representation of the RunInstance object.

        Returns:
            str: A string describing the run instance.
        """
        result = f"RunInstance '{self.id}':\n\tLocation: {self.run_location}"
        if self.command:
            result += f"\n\tCommand: {self.command}"
        if self.args:
            result += f"\n\tArgs: {self.args}"
        return result

    def __repr__(self) -> str:
        """
        Returns a detailed string representation of the RunInstance object for debugging.

        Returns:
            str: A detailed string representation of the object.
        """
        return f"RunInstance(id={self.id}, run_location={self.run_location}, command={self.command}, args={self.args})"

    def get_command_with_args(self) -> Tuple[str, List[str]]:
        """
        Returns the command and arguments for execution.

        Returns:
            Tuple[str, List[str]]: The command and its arguments.
        """
        if self.command and self.args:
            return self.command, self.args
        else:
            raise ValueError("Command and args not set for this RunInstance")

    def get_run_command(self) -> str:
        """
        Constructs the shell command to execute this run instance.

        Returns:
            str: The shell command to execute this run.
        """
        if self.command and self.args:
            return f"{self.command} {' '.join(self.args)}"
        else:
            raise ValueError("No command specified for this RunInstance")

__repr__()

Returns a detailed string representation of the RunInstance object for debugging.

Returns:

Name Type Description
str str

A detailed string representation of the object.
Source code in src/mada_tools/simulation/simutils/models.py 
85
86
87
88
89
90
91
92
def __repr__(self) -> str:
    """
    Returns a detailed string representation of the RunInstance object for debugging.

    Returns:
        str: A detailed string representation of the object.
    """
    return f"RunInstance(id={self.id}, run_location={self.run_location}, command={self.command}, args={self.args})"

__str__()

Returns a human-readable string representation of the RunInstance object.

Returns:

Name Type Description
str str

A string describing the run instance.
Source code in src/mada_tools/simulation/simutils/models.py 
71
72
73
74
75
76
77
78
79
80
81
82
83
def __str__(self) -> str:
    """
    Returns a human-readable string representation of the RunInstance object.

    Returns:
        str: A string describing the run instance.
    """
    result = f"RunInstance '{self.id}':\n\tLocation: {self.run_location}"
    if self.command:
        result += f"\n\tCommand: {self.command}"
    if self.args:
        result += f"\n\tArgs: {self.args}"
    return result

from_dict(data) classmethod

Creates a RunInstance object from a dictionary.

Parameters:

Name Type Description Default
data Dict

Dictionary containing run instance data

 required

Returns:

Type Description
RunInstance

RunInstance object with data from the dictionary
Source code in src/mada_tools/simulation/simutils/models.py 
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
@classmethod
def from_dict(cls, data: Dict) -> "RunInstance":
    """
    Creates a RunInstance object from a dictionary.

    Args:
        data: Dictionary containing run instance data

    Returns:
        RunInstance object with data from the dictionary
    """
    return cls(
        run_location=data.get("run_location"),
        id=data.get("id"),
        command=data.get("command"),
        args=data.get("args"),
    )

get_command_with_args()

Returns the command and arguments for execution.

Returns:

Type Description
Tuple[str, List[str]]

Tuple[str, List[str]]: The command and its arguments.
Source code in src/mada_tools/simulation/simutils/models.py 
 94
 95
 96
 97
 98
 99
100
101
102
103
104
def get_command_with_args(self) -> Tuple[str, List[str]]:
    """
    Returns the command and arguments for execution.

    Returns:
        Tuple[str, List[str]]: The command and its arguments.
    """
    if self.command and self.args:
        return self.command, self.args
    else:
        raise ValueError("Command and args not set for this RunInstance")

get_run_command()

Constructs the shell command to execute this run instance.

Returns:

Name Type Description
str str

The shell command to execute this run.
Source code in src/mada_tools/simulation/simutils/models.py 
106
107
108
109
110
111
112
113
114
115
116
def get_run_command(self) -> str:
    """
    Constructs the shell command to execute this run instance.

    Returns:
        str: The shell command to execute this run.
    """
    if self.command and self.args:
        return f"{self.command} {' '.join(self.args)}"
    else:
        raise ValueError("No command specified for this RunInstance")

to_dict()

Converts the RunInstance object into a JSON-serializable dictionary.

Returns:

Type Description
Dict

A dictionary representation of the RunInstance object.
Source code in src/mada_tools/simulation/simutils/models.py 
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
def to_dict(self) -> Dict:
    """
    Converts the RunInstance object into a JSON-serializable dictionary.

    Returns:
        A dictionary representation of the RunInstance object.
    """
    result = {"id": self.id, "run_location": self.run_location}

    # Include command and args if they are set
    if self.command:
        result["command"] = self.command
    if self.args:
        result["args"] = self.args

    return result

SampleOutputResult dataclass

Represents the result of sample output generation, storing the output path, output type, and optionally the run instances (if necessary).

Attributes:

Name Type Description
output_path str

The path where the samples are written. For "csv" output, this is the path to the CSV file. For "folder" output, this is the path to the directory.
output_type str

The type of output generated (e.g., "csv", "folder").
run_instances List[RunInstance]

A list of RunInstance objects if the output type is "folder".
Source code in src/mada_tools/simulation/simutils/models.py 
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
@dataclass
class SampleOutputResult:
    """
    Represents the result of sample output generation, storing the output path,
    output type, and optionally the run instances (if necessary).

    Attributes:
        output_path (str): The path where the samples are written. For "csv" output, this
            is the path to the CSV file. For "folder" output, this is the path to the directory.
        output_type (str): The type of output generated (e.g., "csv", "folder").
        run_instances (List[RunInstance]): A list of RunInstance objects if the output type is "folder".
    """

    output_path: str
    output_type: str  # e.g., "csv", "folder"
    run_instances: List[RunInstance] = None

    def __str__(self) -> str:
        """
        Returns a human-readable string representation of the SampleOutputResult object.

        Returns:
            str: A string describing the sample output result.
        """
        return (
            f"SampleOutputResult:\n"
            f"  Output path: {self.output_path}\n"
            f"  Output type: {self.output_type}\n"
            f"  Run instances: {self.run_instances}"
        )

    def __repr__(self) -> str:
        """
        Returns a detailed string representation of the SampleOutputResult object for debugging.

        Returns:
            str: A detailed string representation of the object.
        """
        return (
            f"SampleOutputResult(output_path={self.output_path}, "
            f"output_type={self.output_type}, run_instances={self.run_instances})"
        )

__repr__()

Returns a detailed string representation of the SampleOutputResult object for debugging.

Returns:

Name Type Description
str str

A detailed string representation of the object.
Source code in src/mada_tools/simulation/simutils/models.py 
150
151
152
153
154
155
156
157
158
159
160
def __repr__(self) -> str:
    """
    Returns a detailed string representation of the SampleOutputResult object for debugging.

    Returns:
        str: A detailed string representation of the object.
    """
    return (
        f"SampleOutputResult(output_path={self.output_path}, "
        f"output_type={self.output_type}, run_instances={self.run_instances})"
    )

__str__()

Returns a human-readable string representation of the SampleOutputResult object.

Returns:

Name Type Description
str str

A string describing the sample output result.
Source code in src/mada_tools/simulation/simutils/models.py 
136
137
138
139
140
141
142
143
144
145
146
147
148
def __str__(self) -> str:
    """
    Returns a human-readable string representation of the SampleOutputResult object.

    Returns:
        str: A string describing the sample output result.
    """
    return (
        f"SampleOutputResult:\n"
        f"  Output path: {self.output_path}\n"
        f"  Output type: {self.output_type}\n"
        f"  Run instances: {self.run_instances}"
    )