.. currentmodule:: ixmp Python (:mod:`ixmp` package) ============================ .. automodule:: ixmp The |ixmp| application programming interface (API) is organized around three classes: .. autosummary:: Platform TimeSeries Scenario Platform -------- .. autoclass:: Platform :members: Platforms have the following methods: .. autosummary:: add_region add_region_synonym add_unit check_access regions scenario_list set_log_level units The following backend methods are available via Platform too: .. autosummary:: backend.base.Backend.add_model_name backend.base.Backend.add_scenario_name backend.base.Backend.close_db backend.base.Backend.get_doc backend.base.Backend.get_meta backend.base.Backend.get_model_names backend.base.Backend.get_scenario_names backend.base.Backend.open_db backend.base.Backend.remove_meta backend.base.Backend.set_doc backend.base.Backend.set_meta These methods can be called like normal Platform methods, e.g.:: $ platform_instance.close_db() TimeSeries ---------- .. autoclass:: TimeSeries :members: A TimeSeries is uniquely identified on its :class:`Platform` by its :attr:`~.TimeSeries.model`, :attr:`~.TimeSeries.scenario`, and :attr:`~.TimeSeries.version` attributes. For more details, see the :ref:`data model documentation `. A new :attr:`.version` is created by: - Instantiating a new TimeSeries with the same `model` and `scenario` as an existing TimeSeries. - Calling :meth:`Scenario.clone`. TimeSeries objects have the following methods and attributes: .. autosummary:: add_geodata add_timeseries check_out commit discard_changes get_geodata get_meta is_default last_update preload_timeseries read_file remove_geodata remove_timeseries run_id set_as_default set_meta timeseries transact url Scenario -------- .. autoclass:: Scenario :show-inheritance: :members: A Scenario is a :class:`.TimeSeries` that also contains model data, including model solution data. See the :ref:`data model documentation `. The Scenario class provides methods to manipulate :ref:`model data items `. In addition to generic methods (:meth:`init_item`, :meth:`items`, :meth:`list_items`, :meth:`has_item`), there are methods for each of the four item types: - Set: :meth:`init_set`, :meth:`add_set`, :meth:`set`, :meth:`remove_set`, :meth:`has_set` - Parameter: - ≥1-dimensional: :meth:`init_par`, :meth:`add_par`, :meth:`par`, :meth:`remove_par`, :meth:`par_list`, and :meth:`has_par`. - 0-dimensional: :meth:`init_scalar`, :meth:`change_scalar`, and :meth:`scalar`. These are thin wrappers around the corresponding ``*_par`` methods, which can also be used to manipulate 0-dimensional parameters. - Variable: :meth:`init_var`, :meth:`var`, :meth:`var_list`, and :meth:`has_var`. - Equation: :meth:`init_equ`, :meth:`equ`, :meth:`equ_list`, and :meth:`has_equ`. .. autosummary:: add_par add_set change_scalar clone equ has_item has_solution idx_names idx_sets init_item init_scalar items list_items load_scenario_data par read_excel remove_par remove_set remove_solution scalar set solve to_excel var .. _configuration: Configuration ------------- When imported, :mod:`ixmp` reads configuration from the first file named ``config.json`` found in one of the following directories: 1. The directory given by the environment variable ``IXMP_DATA``, if defined, 2. ``${XDG_DATA_HOME}/ixmp``, if the environment variable is defined, or 3. ``$HOME/.local/share/ixmp``. .. tip:: For most users, #2 or #3 is a sensible default; platform information for many local and remote databases can be stored in ``config.json`` and retrieved by name. Advanced users wishing to use a project-specific ``config.json`` can set ``IXMP_DATA`` to the path for any directory containing a file with this name. To manipulate the configuration file, use the ``platform`` command in the ixmp command-line interface:: # Add a platform named 'p1' backed by a local HSQL database $ ixmp platform add p1 jdbc hsqldb /path/to/database/files # Add a platform named 'p2' backed by a remote Oracle database $ ixmp platform add p2 jdbc oracle \ database.server.example.com:PORT:SCHEMA username password # Add a platform named 'p3' with specific JVM arguments $ ixmp platform add p3 jdbc hsqldb /path/to/database/files -Xmx12G # Make 'p2' the default Platform $ ixmp platform add default p2 …or, use the methods of :data:`.ixmp.config`. .. currentmodule:: ixmp .. data:: config An instance of :class:`~.Config`. .. autoclass:: ixmp._config.Config :members: .. autoclass:: ixmp._config.BaseValues :members: Utilities --------- .. currentmodule:: ixmp.util .. automodule:: ixmp.util :members: :exclude-members: as_str_list, check_year, isscalar, year_list, filtered .. autosummary:: diff discard_on_error format_scenario_list maybe_check_out maybe_commit parse_url show_versions update_par to_iamc_layout Utilities for documentation ~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: ixmp.util.sphinx_linkcode_github :members: To use this extension, add it to the ``extensions`` setting in the Sphinx configuration file (usually :file:`conf.py`), and set the required ``linkcode_github_repo_slug``: .. code-block:: python extensions = [ ..., "ixmp.util.sphinx_linkcode_github", ..., ] linkcode_github_repo_slug = "iiasa/ixmp" # Required linkcode_github_remote_head = "feature/example" # Optional The extension uses `GitPython `_ (if installed) or ``linkcode_github_remote_head`` (optional override) to match a local commit to a remote head (~branch name), and construct links like:: https://github.com/{repo_slug}/blob/{remote_head}/path/to/source.py#L123-L456 Utilities for testing ~~~~~~~~~~~~~~~~~~~~~ .. currentmodule:: ixmp.testing .. automodule:: ixmp.testing :members: :exclude-members: pytest_report_header, pytest_sessionstart :special-members: add_test_data .. currentmodule:: ixmp.testing.data .. automodule:: ixmp.testing.data :members: DATA, HIST_DF, TS_DF