{"id":44341622,"url":"https://github.com/denoptim-project/autocompchem","last_synced_at":"2026-02-11T13:03:34.592Z","repository":{"id":64063167,"uuid":"371062532","full_name":"denoptim-project/AutoCompChem","owner":"denoptim-project","description":"Tools for automated computational chemistry","archived":false,"fork":false,"pushed_at":"2026-02-05T14:20:37.000Z","size":92345,"stargazers_count":4,"open_issues_count":6,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-06T01:00:42.623Z","etag":null,"topics":["computational-chemistry","java","molecular-modeling","quantum-chemistry"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/denoptim-project.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-05-26T14:26:00.000Z","updated_at":"2026-02-05T14:20:40.000Z","dependencies_parsed_at":"2025-09-19T00:15:04.110Z","dependency_job_id":null,"html_url":"https://github.com/denoptim-project/AutoCompChem","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/denoptim-project/AutoCompChem","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denoptim-project%2FAutoCompChem","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denoptim-project%2FAutoCompChem/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denoptim-project%2FAutoCompChem/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denoptim-project%2FAutoCompChem/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/denoptim-project","download_url":"https://codeload.github.com/denoptim-project/AutoCompChem/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/denoptim-project%2FAutoCompChem/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29333155,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-11T12:42:24.625Z","status":"ssl_error","status_checked_at":"2026-02-11T12:41:23.344Z","response_time":97,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["computational-chemistry","java","molecular-modeling","quantum-chemistry"],"created_at":"2026-02-11T13:03:29.008Z","updated_at":"2026-02-11T13:03:34.587Z","avatar_url":"https://github.com/denoptim-project.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AutoCompChem\n\n![Anaconda_Version](https://anaconda.org/denoptim-project/autocompchem/badges/version.svg) ![Anaconda_last](https://anaconda.org/denoptim-project/autocompchem/badges/latest_release_date.svg) ![Anaconda_Platforms](https://anaconda.org/denoptim-project/autocompchem/badges/platforms.svg) ![Anaconda_License](https://anaconda.org/denoptim-project/autocompchem/badges/license.svg) ![Anaconda_downloads](\nhttps://anaconda.org/denoptim-project/autocompchem/badges/downloads.svg)\n\nAutoCompChem (or ACC) is a collection of tools used to automatise computational chemistry tasks.\n\n## Installation from Conda\nFrom within any conda environment you can install AutoCompChem as follows\n```\nconda install -c denoptim-project autocompchem\n```\nNow the `autocompchem` command should be available. Try to run the following to start using it:\n```\nautocompchem -h\n```\n\n## Installation from Source\nDownload and extract the \u003ca href=\"https://github.com/denoptim-project/AutoCompChem/releases/latest\"\u003elatest release\u003c/a\u003e to create a folder we'll call `ACC_HOME`. In the following, remember to replace `$ACC_HOME` with the pathname leading to the extracted distribution of AutoCompChem.\n\nMake sure you have an environment that includes JAVA and Maven. Such environment, which we call `acc_devel`, can be created by manual installation of both JAVA and Maven, or it can be created using conda:\n```\ncd $ACC_HOME\nconda env create -f environment.yml\nconda activate acc_devel\n```\n\nVerify the requirements by running these two commands: Both should return a message declaring which version has been installed.\n```\njavac -version\nmvn -version\n```\n\nNow, you can build AutoCompChem with\n```\nmvn package\n```\n\nFinally, you can call AutoCompChem using a command like the following (NB: replace `$ACC_HOME` and `${VERSION}` with the values that apply to the version you have installed):\nOn Linux/Mac terminals and Windows GitBash:\n```\njava -jar $ACC_HOME/target/autocompchem-${VERSION}-jar-with-dependencies.jar\n```\nInstead, on Windows Anaconda prompt (assuming you have created the environment with any version of conda):\n```\njava -jar $ACC_HOME\\target\\autocompchem-${VERSION}-jar-with-dependencies.jar\n```\nYou should create an alias to the appropriate command, depending on your operating system. For example, on a Unix system running a BASH terminal the alias would look like this (NB: replace `$ACC_HOME` and `${VERSION}` with the values that apply to the version you have installed):\n```\nautocompchem=\"java -jar $ACC_HOME/target/autocompchem-${VERSION}-jar-with-dependencies.jar\"\n```\n\n## Testing\nMany self-evaluating tests are available to verify the functionality of AutoCompChem. These tests are also examples of usage. See under the `test` folder or run them all to verify the functionality of your installation by running\n```\ncd $ACC_HOME\n./test/run_tests.sh\n```\n\n## Usage\nAutoCompChem can perform a number of tasks, i.e., operations useful in various contexts of any computational chemistry project. Run the following \"help\" command to get the list of supported tasks:\n```\nautocompchem -h\n```\nFrom the message written by running the \"help\" command, choose a task you are interested in, say `\u003cchosen_task\u003e`, and repeat the above \"help\" command adding `-t \u003cchosen_task\u003e` (NB: in this document we use `\u003c...\u003e` to indicate any unspecified string. For example, `\u003cchosen_task\u003e` could be replaced by `mutateAtoms` or any other task name):\n```\nautocompchem -h -t \u003cchosen_task\u003e\n```\nThis will give the complete documentation on any available command line argument that may be used to define any settings when performing the `\u003cchosen_task\u003e`. Arguments may be specified in any order, and are used either as *keywords* or *keyword:value* pairs. The *keyword* is always case-insentitive, but the value is case sensitive. The syntax for specifying any argument is\n```\n--\u003ckeyword\u003e\n```\nfor any argument that does not require a value, and\n```\n--\u003ckeyword\u003e \u003cvalue\u003e\n```\nfor those requiring a value. Quotation marks should be used as usual, when the value may contain spaces or other characters that the command line would interprete in unintended ways. E.g., `--\u003ckeyword\u003e \"\u003cvalue1\u003e \u003cvalue2\u003e \u003cvalue3\u003e\"`.\n\nThe actual execution of a task by AutoCompChem is called a *job*. AutoCompChem can perform single jobs or multiple jobs in a single call, i.e., workflows, where AutoCompChem performs a series of possibly nested tasks in sequence or in parallel. The settings of any job can be defined in three ways: as command line arguments, or in a [parameters' file](#parameters-file), or in a [JSON job details file](#job-details-file). The choice between these three ways to control AutoCompChem depends on the complexity of the job: for getting help or running simple jobs, the command line interface is the most effective, but becomes impractical if many complex arguments have to be used. In the latter case, the [parameters' file](#parameters-file) becomes more suitable than the command line interface, but if the complexity increases by nesting multiple jobs into a workflow, then a [JSON job details file](#job-details-file) allows to exploit the functionality of any good text editor to easily navigate the details of each part of the workflow.\n\n### Single Job\n#### Parameters File\nAny list of command line arguments needed to perform a task can also be written into a text file, which is internally referred as a *parameters' file*. The following syntax applies:\n```\nTASK: \u003cchosen_task\u003e\n\u003ckeywordA\u003e\n\u003ckeywordB\u003e: \u003cvalue1\u003e \u003cvalue2\u003e \u003cvalue3\u003e\n...\n```\nThe order of the lines is irrelevant. Each line is meant to hold a single *keyword* or a single *keyword:value* pair, unless the value constraints newline characters, in which case the `$START` and `$END` strings should be used to identify a multiline block of text that will be interpreted as a single line when parsing the parameters file. For example:\n```\nTASK: \u003cchosen_task\u003e\n$START\u003ckeywordC\u003e: \u003cvalue1\u003e\n\u003cvalue2\u003e\n\u003cvalue3\u003e\n$END\n\u003ckeywordD\u003e: \u003cvalueD\u003e\n...\n```\n\n\u003e [!NOTE]\n\u003e While command line processing can exploit all command line functionality (e.g., use environmental variables and wildcards in pathnames), this cannot be done in parameters' files.\n\nTo use a parameters' file, call AutoCompChem and give it the pathname to the parameters' file as value of the `-p` (`--params`) argument:\n```\nautocompchem -p \u003cpath_to_parameters_file\u003e\n```\n\n##### Example\nThe parameters file [examples/single_job.params](examples/single_job.params) defines a simple task meant to change the identity of any Cl atom into Br in a given SDF file:\n```\nTASK: mutateAtoms\nINFILE: mol.sdf\nSMARTS: [Cl] element Br\nOUTFILE: mol_atomEdited.sdf\n```\nTo perform this task you do the following:\n```\ncd $ACC_HOME/examples\nautocompchem -p single_job.params\n```\nThe result is saved into file `mol_atomEdited.sdf`, which you can visualize with any molecular visualization software package (e.g., [Jmol](https://jmol.sourceforge.net/)).\nMany examples of parameters files are available under the [test folder](test), where they are named `*.params`.\n\n#### Job Details File\nParameters may also be provided by defining jobs in [JSON format](https://en.wikipedia.org/wiki/JSON). This format is slightly more verbose than the parameters' file format, but is a standard format that can be manipulated by other software. For instance, it allows text editors to efficiently navigate the nested structure of the data stored in a JSON format. To define an AutoCompChem job (i.e., an *ACCJob*) in a JSON file use the following syntax:\n```\n{\n  \"jobType\": \"ACCJob\",\n  \"params\": [\n    {\n      \"reference\": \"task\",\n      \"value\": \"\u003cchosen_task\u003e\"\n    },\n    {\n      \"reference\": \"\u003ckeywordA\u003e\"\n    },\n    {\n      \"reference\": \"\u003ckeywordB\u003e\",\n      \"value\": \"\u003cvalue1\u003e \u003cvalue2\u003e \u003cvalue3\u003e\"\n    },\n    {\n      \"reference\": \"\u003ckeywordC\u003e\",\n      \"value\": \"\u003cvalue1\u003e\\n\u003cvalue2\u003e\\n\u003cvalue3\u003e\"\n    }\n  ]\n}\n```\nNote that any command line argument is defined in terms of a `reference`, i.e., the string identifying the argument, and `value`, which is the actual value of that argument, if any.\nTo use a job details file, call AutoCompChem and give it the pathname to the job details file as value of the `-j` (`--job`) argument:\n```\nautocompchem -j \u003cpath_to_job_details_file\u003e\n```\n\nThe job details file [examples/single_job.json](examples/single_job.json) defines the same job performed in the previous example, i.e., a job meant to change the identity of any Cl atom into Br in a given SDF file.\nMany other examples are available under the [test folder](test). However, note that the JSON format can be used to define many kinds on objects, including jobs that are not meant to be performed by AutoCompChem, e.g., any molecular modeling job. Therefore, not all ´.json´ files in the test folder define ACCJobs.\n\nJSON job details files can be conveniently generated from parameter's file (and vice versa) by the `convertJobDefinition` task.\n\n### Multiple Jobs\nAutoCompChem can also perform multiple tasks, hence *jobs*, whether in a sequence (i.e., a workflow), or in parallel (i.e., a batch). Either way, the list of jobs to perform, whether steps of a workflow or independent jobs to be performed in parallel, are defined within a job that acts as a container. Such container may itself be contained in a parent job resulting in a recursive structure.\nThe distinction between serial and parallel execution is controlled by the jobs' container: if the container defines the `PARALLELIZE: \u003cthreads\u003e` key-value pair, then the contained jobs will be executed in parallel using a number of asynchronous threads equal to the value specified by `\u003cthreads\u003e`.\n\nHere are the two ways to define AutoCompChem jobs meant to contain sub-jobs, whether serial or parallel, in parameter's file format or job details file format:\n\n* **Parameters files**: the `JOBSTART` and `JOBEND` keyword are used to surround the settings and content of a single job (NB: empty lines are only used to increase readability, but they are not needed):\n  ```\n  JOBSTART\n  TASK: \u003ctask1\u003e\n  ...\n  JOBEND\n\n  JOBSTART\n  TASK: \u003ctask2\u003e\n  ...\n  JOBEND\n  ```\n  This parameters file defines a two-step *sequential* job. Notably, the container job can be effectively omitted from this syntax unless it needs to be altered in some way. For instance, you may alter the container job by requesting to run its sub jobs in parallel:\n  ```\n  JOBSTART\n  PARALLELIZE: 2\n\n  JOBSTART\n  TASK: \u003ctask1\u003e\n  ...\n  JOBEND\n\n  JOBSTART\n  TASK: \u003ctask2\u003e\n  ...\n  JOBEND\n\n  JOBEND\n  ```\n  Now, the two tasks will be executed in parallel within the parent job that acts as a container.\n\n  For example, files [examples/sequential.params](examples/sequential.params) and [examples/parallel.params](examples/parallel.params) can be used to perform the same tasks either sequentially or in parallel under the [examples](examples) folder.\n\n* **Job details files**:\n  The jobs contained in a job container are listed under the ´steps´ section, irrespectively on whether the execution is meant to be serial or parallel.\n  ```\n  {\n    \"jobType\": \"ACCJob\",\n    \"steps\": [\n      {\n        \"jobType\": \"ACCJob\",\n        \"params\": [\n          {\n            \"reference\": \"task\",\n            \"value\": \"\u003ctask1\u003e\"\n          },\n          ...\n        ]\n      },\n      {\n        \"jobType\": \"ACCJob\",\n        \"params\": [\n          {\n            \"reference\": \"task\",\n            \"value\": \"\u003ctask2\u003e\"\n          },\n          ...\n        ]\n      }\n    ]\n  }\n  ```\n  Adding the JSON-formatted version of the `PARALLELIZE: \u003cthreads\u003e` parameter to the job container will make the contained jobs run in parallel using the given number of threads:\n  ```\n  {\n    \"jobType\": \"ACCJob\",\n    \"params\": [\n      {\n        \"reference\": \"parallelize\",\n        \"value\": 2\n      }\n    ],\n    \"steps\": [\n      ...\n    ]\n  }\n  ```\n\n  For example, see files [examples/sequential.json](examples/sequential.json) and [examples/parallel.json](examples/parallel.json) can be used to perform the same tasks either sequentially or in parallel under the [examples](examples) folder.\n\n### General Job Parameters\nThe following parameters can be used in any kind of job, but may also be ineffective. For example, parallelization settings takes effect only on sub jobs, so they are ineffective for jobs that contain no sub jobs. Yet, these parameters can be used as any other parameter as command line arguments, or in parameters files, or in job details file, using the corresponding format.\n* Reference name: `Parallelize`, value: `int` - specified the number of threads to use when running the  sub jobs (i.e., the \"steps\" contained in the job where this parameter is specified).\n* Reference name: `WorkDir`, value: `pathname` - specifies the pathname to a folder that should be considered the work space for the job. For jobs with this parameter, any file operation replying on the value of the present work directory will consider the given pathname. For example, reading/writing of a file defined only by its name, will occur under the folder defined by the `WorkDir` parameter. Therefore, the combination of `InFile: filename.txt` and `WorkDir: some/path` will make AutoCompChem use file `some/path/filename.txt` as value of parameter `InFile`. This mechanism applied to all files, but those defined in the `copyToWorkDir` parameter (see below). The value of `pathname` can be an absolute or relative path. In the latter case, the path is considered relative to the location where the AutoCompChem command is started (i.e., the `user.dir` of the Java Virtual Machine running AutoCompChem). The configuration of a curtomized work directory has effect only within the job where such configuration is given, not on sub jobs).\n* Reference name: `copyToWorkDir`, value: `pathname[,pathname[,pathname[...]]]` - specifies a comma-separated list of pathnames to files that should be copied into the work directory (whether customized by `WorkDir` or not). The pathnames specified in the value of this parameter ignore the value of `WorkDir` and consider as present work directory the location from where the AutoCompChem command is started (i.e., the `user.dir` of the Java Virtual Machine running AutoCompChem). The files are copied as part of the Job's execution, not beforehand. Hence, so these files to be copied may not exist when the job is defined, but are expected to exist when the job runs. A Warning is thrown if any such file is not found at the job's execution time.\n\n## Acknowledgments\nThe Research Council of Norway (RCN) is acknowledged for financial support.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdenoptim-project%2Fautocompchem","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdenoptim-project%2Fautocompchem","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdenoptim-project%2Fautocompchem/lists"}