modelon.impact.client package

Subpackages

Submodules

modelon.impact.client.client module

This module provides an entry-point to the client APIs.

class Client(url=None, interactive=None, credential_manager=None, context=None, jupyterhub_credential_manager=None)

Bases: object

This Class contains methods to authenticate logins, create new workspaces and upload or fetch existing workspaces.

Parameters:

  • url (Optional[str]) – The URL for Modelon Impact client host. Defaults to the value specified by environment variable ‘MODELON_IMPACT_CLIENT_URL’ if set else uses the URL ‘https://impact.modelon.cloud/’.

  • interactive (Optional[bool]) –

    If True the client will prompt for an API key if no other login information can be found. An API key entered for this prompt will be saved to disk and re-used next time the Client is instantiated. If False no prompt will be given if no other login information can be found and login will be done as if no API key was given (anonymous login).

    For scripts and notebooks that are running interactively by a user in a shell it is recommended to use interactive=True. For scripts or applications that are automated or for other reasons won’t have a user ready to enter an API key it is recommended to use interactive=False.

    Default is False. It is possible to change the default value through the environment variable ‘MODELON_IMPACT_CLIENT_INTERACTIVE’.

  • credential_manager (Optional[CredentialManager]) – Help class for managing credentials for the Impact server. Default is None and then the default credential manager is used.

  • context (Optional[Context]) – Request contexts to pass data alongside a HTTP request. Default is None and then the default context is used.

Example:

from modelon.impact.client import Client

client = Client(url=impact_url)
client = Client(url=impact_url, interactive=True)
convert_workspace(workspace_id, backup_name=None)

Converts a workspace of an old version up to the new version the server is using.

Parameters:

  • workspace_id (str) – The ID of the workspace to convert to the latest

  • backup_name (Optional[str]) – If given then a backup will be created with this

  • None. (name. Defaults to) –

Return type:

WorkspaceConversionOperation

Returns:

The workspace conversion operation

Example:

workspace = client.convert_workspace(workspace_id, backup_name='old save')
.wait()
create_workspace(workspace_name)

Creates and returns a Workspace. Returns a workspace class object.

Parameters:

workspace_name (str) – The name of the workspace to create.

Return type:

Workspace

Returns:

The created workspace class object.

Example:

workspace = client.create_workspace('my_workspace')
get_executions(workspace_id=None)

Yields running/active executions.

Parameters:

workspace_id (Optional[str]) – The id of the workspace.

Yields:

An ExperimentOperation or a ModelExecutableOperation class.

Return type:

Iterable[Union[ExperimentOperation, ModelExecutableOperation, None]]

Example:

list(client.get_executions())
get_me()

Return the User class object for the logged in user.

Example:

user = client.get_me()
user_tenant_group_name = user.tenant.group_name
Return type:

User

get_project(project_id, vcs_info=True)

Returns a project class object.

Parameters:

  • project_id (str) – The id of the project.

  • vcs_info (bool) – If True, the versioning details are returned for the project(if under version control).

Return type:

Project

Returns:

Project class objects.

Example:

client.get_project('hcbhsb11313321')
get_project_matchings(shared_definition)

Returns all projects matchings that would happen during a workspace import. As import will fail if there are multiple possible matchings of local projects for a project, this method is used to get these matchings which can be resolved to an unequivocal ‘selection’. Selections are used as (optional) input to the import_workspace_from_shared_definition method.

Parameters:

shared_definition (WorkspaceDefinition) – The workspace definition for the shared workspace

Return type:

ProjectMatchings

Returns:

A ProjectMatchings class object.

Example:

# Import with conflicts(Multiple existing projects matches the URI)
# Programatic workflow to resolve conflicts
matchings = client.get_project_matchings(shared_definition)
# Assume the first in list of matchings is good enough:
selections = [entry.get_selection(index=0) for entry in matchings.entries]
imported_workspace = client.import_from_shared_definition(
    shared_definition, selections
).wait()

# Interactive workflow
matchings = client.get_project_matchings(shared_definition)
selections = matchings.make_selections_interactive()
imported_workspace = client.import_workspace_from_shared_definition(
    shared_definition, selections
).wait()
get_projects(vcs_info=True, project_type=None, storage_location=None)

Returns a list of project class object.

Parameters:

  • vcs_info (bool) – If True, the versioning details are returned for the projects under version control.

  • project_type (Optional[ProjectType]) – Used to filter so only projects of a specified ProjectType are returned. If not given all project types are returned.

  • storage_location (Optional[StorageLocation]) – Used to filter so only projects of a specified StorageLocation are returned. If not given all project in all storage locations are returned.

Return type:

List[Project]

Returns:

A list of Project class objects.

Example:

from modelon.impact.client import ProjectType, StorageLocation

client.get_projects()
client.get_projects(
    project_type=ProjectType.LOCAL,
    storage_location=StorageLocation.USERSPACE
)
get_published_workspaces_client()

Return the PublishedWorkspacesClient class object.

Example:

pw_client = client.get_published_workspaces_client()
pw_client.get_by_id("2h98hciwsniucwincj")
Return type:

PublishedWorkspacesClient

get_workspace(workspace_id)

Returns a Workspace class object.

Parameters:

workspace_id (str) – The ID of the workspace.

Return type:

Workspace

Returns:

Workspace class object.

Example:

client.get_workspace('my_workspace')
get_workspace_by_name(workspace_name)

Returns a list of Workspace class objects with the given name.

Parameters:

workspace_name (str) – The name of the workspace.

Return type:

List[Workspace]

Returns:

A list of workspace class objects with the given name.

Example:

workspaces = client.get_workspace_by_name('TestWorkspace')
get_workspaces(only_app_mode=False, name=None, sharing_id=None)

Returns a list of Workspace class object.

Return type:

List[Workspace]

Returns:

A list of Workspace class objects.

Example:

workspaces = client.get_workspaces()
import_project_from_zip(path_to_project)

Imports a Project from a compressed(.zip) project file. Returns the project class object.

Parameters:

  • path_to_project (str) – The path for the compressed project(.zip)

  • uploaded. (to be) –

Return type:

ProjectImportOperation

Returns:

A ProjectImportOperation class object.

Example:

client.import_project_from_zip(path_to_project).wait()
import_workspace_from_shared_definition(shared_definition, selections=None)

Imports a Workspace from a shared workspace definition.

Parameters:

  • shared_definition (WorkspaceDefinition) – The workspace definition for the shared workspace

  • selection – Optional list of Selection class objects. This can be specified

  • URI. (if there are multiple existing projects with the same version control) –

Return type:

WorkspaceImportOperation

Returns:

A WorkspaceImportOperation class object.

Example:

# Import with no conflicts
client.import_workspace_from_shared_definition(shared_definition).wait()

# Import with conflicts(Multiple existing projects matches the URI)
# Programatic workflow to resolve conflicts

matchings = client.get_project_matchings(shared_definition)
# Assume the first in list of matchings is good enough:
selections = [entry.get_selection(index=0) for entry in matchings.entries]
imported_workspace = client.import_workspace_from_shared_definition(
    shared_definition, selections
).wait()

# Interactive workflow
matchings = client.get_project_matchings(shared_definition)
selections = matchings.make_selections_interactive()
imported_workspace = client.import_workspace_from_shared_definition(
    shared_definition, selections
).wait()
import_workspace_from_zip(path_to_workspace)

Imports a Workspace from a compressed(.zip) workspace file. Similar to upload_workspace, but gives more control for getting the workspace async. Returns an WorkspaceImportOperation class object.

Parameters:

  • path_to_workspace (str) – The path for the compressed

  • workspace (.zip) –

Return type:

WorkspaceImportOperation

Returns:

A WorkspaceImportOperation class object.

Example:

client.import_workspace_from_zip(path_to_workspace).wait()
upload_workspace(path_to_workspace)

Imports a Workspace from a compressed(.zip) workspace file. Returns the workspace class object of the imported workspace. Similar to import_workspace_from_zip, but does the import in one go.

Parameters:

  • path_to_workspace (str) – The path for the compressed workspace(.zip)

  • uploaded. (to be) –

Return type:

Workspace

Returns:

Workspace class object.

Example:

workspace = client.upload_workspace(path_to_workspace)
class Execution(kind, workspace_id, id)

Bases: object

classmethod from_dict(execution)
Return type:

Execution

id: str
kind: ExecutionKind
workspace_id: str
class ExecutionKind(value)

Bases: Enum

An enumeration.

COMPILATION = 'COMPILATION'
EXPERIMENT = 'EXPERIMENT'
class ProjectMatching(entry_id, vcs_uri, projects)

Bases: object

entry_id: str
get_selection(index)

Returns the selection given the index of the selected project.

Parameters:

index (int) – The index of the selected project

Return type:

Selection

Returns:

A Selection class object.

Example:

matchings = client.get_project_matchings(imported_workspace_definition)
selection = matchings.entries[0].get_selection(index=0)

client.import_workspace_from_shared_definition(shared_definition).wait()
make_selection_interactive()

Returns an interactively chosen Selection object.

Return type:

Selection

Returns:

A Selection class object.

Example:

matchings = client.get_project_matchings(imported_workspace_definition)
selection = matchings.entries[0].make_selection_interactive()
projects: List[Project]
vcs_uri: str
class ProjectMatchings(entries)

Bases: object

entries: List[ProjectMatching]
make_selections_interactive()

Returns a list of Selection class objects based on interactive input from users. As import will fail if there are multiple possible matchings of local projects for a project, this method is used to resolve to an unequivocal ‘selection’. The list of preferred Selection objects could be specified during workspace import in the import_workspace_from_shared_definition method.

Return type:

List[Selection]

Returns:

A a list of Selection class objects.

Example:

# Interactive workflow
matchings = client.get_project_matchings(shared_definition)
selections = matchings.make_selections_interactive()
imported_workspace = client.import_workspace_from_shared_definition(
    shared_definition, selections
).wait()
class Selection(entry_id, project)

Bases: object

entry_id: str
project: Project
to_dict()
Return type:

Dict[str, Any]

class Tenant(id, group_name)

Bases: object

classmethod from_dict(tenant_data)
Return type:

Tenant

group_name: str
id: str
class User(id, username, firstname, last_name, email, license, roles, tenant)

Bases: object

email: str
firstname: str
classmethod from_dict(data)
Return type:

User

id: str
last_name: str
license: str
roles: List[str]
tenant: Tenant
username: str

modelon.impact.client.configuration module

class Experimental(fn)

Bases: object

get_client_experimental()

Returns the default for if experimental client methods should be enabled or not.

Can be overridden by the environment variable IMPACT_PYTHON_CLIENT_EXPERIMENTAL.

Return type:

bool

get_client_experiments_v3_experimental()

If the client should use the new experimental V3 schema for experiments.

Can be overridden by the environment variable IMPACT_PYTHON_CLIENT_V3_EXPERIMENTS.

Return type:

bool

get_client_interactive()

Returns the default for if client will run interactive or not if unspecified.

Can be overridden by the environment variable MODELON_IMPACT_CLIENT_INTERACTIVE.

Return type:

bool

get_client_url()

Returns the default URL the client will use if unspecified.

Can be overridden by the environment variable MODELON_IMPACT_CLIENT_URL.

Return type:

str

modelon.impact.client.credential_manager module

class CredentialManager(file_id='api.key', env_names=['MODELON_IMPACT_CLIENT_API_KEY'], interactive_help_text='Enter Modelon Impact API key:')

Bases: object

get_key(interactive=False)
Return type:

Optional[str]

get_key_from_env()
Return type:

Optional[str]

get_key_from_file()
Return type:

Optional[str]

get_key_from_prompt()
Return type:

str

write_key_to_file(api_key)
Return type:

None

modelon.impact.client.exceptions module

exception Error

Bases: Exception

exception ExternalResultUploadError

Bases: Error

exception IllegalContentImport

Bases: Error

exception IllegalFMUImport

Bases: Error

exception IllegalProjectImport

Bases: Error

exception IllegalWorkspaceConversion

Bases: Error

exception IllegalWorkspaceExport

Bases: Error

exception IllegalWorkspaceImport

Bases: Error

exception NoAssignedLicenseError

Bases: Error

exception NoAssociatedPublishedWorkspaceError

Bases: Error

exception NoSuchCustomArtifactError

Bases: Error

exception OperationCompleteError

Bases: Error

exception OperationFailureError

Bases: Error

classmethod for_operation(operation_name)
Return type:

OperationFailureError

exception OperationNotCompleteError

Bases: Error

classmethod for_operation(operation_name, status)
Return type:

OperationNotCompleteError

exception OperationTimeOutError

Bases: Error

exception RemotePublishedWorkspaceLinkError

Bases: Error

exception UnsupportedSemanticVersionError

Bases: Error

modelon.impact.client.options module

class BaseExecutionOptions(values, custom_function_name)

Bases: Mapping, ABC

Base class for the simulation, compiler, solver and runtime options settings.

with_values(**modified)

Sets/updates the options.

Parameters:

parameters – A key-worded, variable-length argument list of options.

Return type:

Any

Example:

cmp_opts = custom_function.get_compiler_options().with_values(
    c_compiler='gcc')
runtime_opts = custom_function.get_runtime_options().with_values(
    cs_solver=0)
sol_opts = custom_function.get_solver_options().with_values(rtol=1e-7)
sim_opts = custom_function.get_simulation_options().with_values(ncp=500)
class CompilerOptions(values, custom_function_name)

Bases: BaseExecutionOptions

class ProjectExecutionOptions(data, name)

Bases: object

property compiler_options: CompilerOptions
property custom_function: str
property runtime_options: RuntimeOptions
property simulation_options: SimulationOptions
property solver_options: SolverOptions
to_dict()
Return type:

Dict[str, Any]

class RuntimeOptions(values, custom_function_name)

Bases: BaseExecutionOptions

class SimulationOptions(values, custom_function_name)

Bases: BaseExecutionOptions

with_result_filter(filter)

Sets the variable filter for results.

Parameters:

filter (List[str]) – A list of filter patterns for choosing which variables to actually store result for. The syntax can be found in https://en.wikipedia.org/wiki/Glob_(programming). An example for filter is *der, which would stores all variables ending with der.

Return type:

SimulationOptions

Example:

sim_opts = custom_function.get_simulation_options().with_result_filter(
    filter = ["*.phi"])
class SolverOptions(values, custom_function_name)

Bases: BaseExecutionOptions

modelon.impact.client.published_workspace_client module

class PublishedWorkspaceAccess(sharing_id, requested_id, requested_username, published_workspace=None)

Bases: object

published_workspace: Optional[PublishedWorkspace] = None
requested_id: str
requested_username: str
sharing_id: str
class PublishedWorkspaceAccessKind(value)

Bases: Enum

An enumeration.

REQUESTED_BY_ME = 'requestedByMe'
REQUESTED_FROM_ME = 'requestedFromMe'
SHARED_BY_ME = 'sharedByMe'
SHARED_WITH_ME = 'sharedWithMe'
class PublishedWorkspacesClient(service)

Bases: object

find(*, name='', first=0, maximum=20, has_data=False, owner_username='', type=None, group_name=None)

Returns a list of published workspaces. The snapshots could be filtered based on the key-worded arguments.

Parameters:

  • name (str) – Name of the workspace.

  • first (int) – Index of first matching resource to return.

  • maximum (int) – Maximum number of resources to return.

  • has_data (bool) – If true, filters with

  • false (status==PublishedWorkspaceUploadStatus.CREATED. If) –

  • everything. (returns) –

  • owner_username (str) – If true, only workspaces published by the specified

  • listed. (user are) –

  • type (Optional[PublishedWorkspaceType]) – Filter so only published workspace of a specified type are returned. If not given all published workspace types are returned.

  • group_name (Optional[str]) – Group name to query published workspaces for. Only a user with impact-sys-admin role can query published workspaces shared with a group other than his own.

Return type:

List[PublishedWorkspace]

Returns:

A list of published workspace class objects.

Example:

pw_client = client.get_published_workspaces_client()
pw_client.find()
get_by_id(sharing_id, request_if_no_access=False)

Returns the published workspace class object with the given ID.

Parameters:

  • sharing_id (str) – ID of the published workspace.

  • request_if_no_access (bool) – Request access if user doesn’t have access.

Return type:

Optional[PublishedWorkspace]

Returns:

The published workspace class object.

Example:

pw_client = client.get_published_workspaces_client()
pw_client.get("2h98hciwsniucwincj")

Module contents